Reference

Automation and MCP access

Supported automation paths, hosted MCP authentication, and the exact routes exposed by the optional local HTTP gateway.

The production automation contract is MCP. Most integrations should use one of these two paths:

The hosted MCP endpoint for an MCP-aware client or service.
The optional machine-local HTTP gateway when a local process cannot speak stdio.

The service's internal backend REST routes are not the public automation contract. Do not build a client by copying requests from the dashboard or guessing /api/v1 backend paths; use the hosted MCP contract or the local gateway documented here.

Hosted MCP

The normal endpoint is:

Code

https://mcp.contextstream.io/mcp?default_context_mode=fast

For a hand-written connection, send the API key as a header, not in the URL:

JSON

{
  "type": "http",
  "url": "https://mcp.contextstream.io/mcp?default_context_mode=fast",
  "headers": {
    "X-ContextStream-API-Key": "YOUR_API_KEY"
  }
}

The setup wizard is preferred because it also writes current client identity, tool-surface, capture, and compatibility metadata. The minimal example above is useful for a custom client, but it is not a byte-for-byte copy of a managed editor config.

Create and revoke keys in the dashboard. Use one key per machine or service, store it in a secret manager or machine-only config, and never commit it. contextstream-mcp verify-key --json is a suitable preflight for scripts.

Local HTTP gateway

The installed MCP binary can expose its tool registry over HTTP:

Terminal

contextstream-mcp http --host 127.0.0.1 --port 8787

Always pass the loopback host for a machine-local gateway. The command's raw bind default is 0.0.0.0, and authentication is off unless explicitly enabled; starting that default on an untrusted network exposes a writable agent tool surface.

The gateway still calls ContextStream's hosted search and memory service. It is a transport adapter, not an offline or local-only data plane.

Streamable MCP routes

Method	Route	Purpose
`POST`	`/mcp`	Generic MCP Streamable HTTP endpoint
`POST`	`/chatgpt`	ChatGPT-specific endpoint over the same handler
`POST`	`/claude`	Claude-specific endpoint over the same handler
`POST`	`/client`	Generic client-specific endpoint over the same handler
`GET`	`/health`	Health check
`GET`	`/metrics`	Prometheus metrics

The gateway also exposes OAuth discovery documents at /.well-known/oauth-protected-resource, /.well-known/oauth-authorization-server, and /.well-known/openid-configuration. Health, metrics, and discovery stay unauthenticated even when request authentication is required.

An ordinary MCP client should use /mcp. The client-specific endpoints force the complete ContextStream tool surface for their intended integrations; they are not separate data stores.

Compatibility HTTP routes

The local gateway also carries a small compatibility API under /api/v1:

Method	Route	Purpose
`POST`	`/api/v1/rpc`	JSON-RPC endpoint
`POST`	`/api/v1/initialize`	Initialize the MCP connection
`GET`	`/api/v1/tools/list`	List exposed tools
`POST`	`/api/v1/tools/call`	Call a named tool from the request body
`POST`	`/api/v1/tools/:name`	Call the tool named in the path
`GET`	`/api/v1/health`	Health check
`GET`	`/api/v1/stream`	Server-sent event stream

The JSON-RPC endpoint recognizes initialize, tools/list, tools/call, and MCP notification methods. A minimal sequence is:

JSON

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"internal-service","version":"1.0"}}}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"help","arguments":{"action":"version"}}}

Send each object as a separate request to /api/v1/rpc. Generate the arguments for any other call from the schema returned by tools/list.

Securing the local gateway

To require credentials on non-public routes:

Terminal

export MCP_HTTP_REQUIRE_AUTH=true
contextstream-mcp http --host 127.0.0.1 --port 8787

Authenticated requests may use X-ContextStream-API-Key, X-API-Key, or an Authorization: Bearer … value. X-ContextStream-JWT is also recognized. If this gateway should verify HS256 JWTs itself, set a strong CONTEXTSTREAM_JWT_SECRET; without that secret, do not describe the process as locally verifying bearer JWT signatures.

Requiring a credential does not add TLS. Keep the service on loopback, or put it behind an authenticated TLS reverse proxy with a narrow network policy. Do not expose the gateway directly to the public internet.

Scope and concurrent callers

Initialize each conversation and retain the returned MCP session identifier. Send that identifier on later requests when the client protocol supports it. The gateway combines authenticated identity and MCP session identity to keep concurrent callers from silently rescoping one another.

Inside tool arguments, reuse workspace and project IDs returned by initialization/context. Do not guess scope from a display name when a write is involved.

Errors and compatibility

HTTP 401 means a required credential was missing or rejected.
A JSON-RPC error means the method, tool name, schema, or execution failed; inspect its code and message rather than treating a successful HTTP status as a successful tool result.
MCP results can contain readable text and structuredContent; preserve both when building a programmatic client.
Tool availability depends on the configured toolset, account, deployment, and connected integrations. Always use the current tools/list.
Hosted-only domains such as charts and asynchronous export/aggregate jobs may be absent or unavailable in a locally built gateway.

For the domain-level behavior behind the schemas, see the MCP tool reference.