Skip to main content

Gateway MCP surface

Before you begin​

You need:

  • an agent publication with a resolved public hostname
  • an active Access Key or Gateway Key authorized for that publication
  • an MCP client that supports remote streamable HTTP

First open https://<your-published-hostname>/mcp with the client configuration below. A localhost gateway or an unpublished agent does not satisfy this surface.

This is a separate surface from:

  • provider: mcp in gateway config, which routes gateway traffic to an external MCP backend
  • tool_servers, which declares config-managed tool-server metadata for validation and discovery

Current connection shape​

Use a published agent hostname in the form:

https://<publication-key>.<public_hostname_suffix>/mcp

Authenticate with your Access Key (or Gateway Key) as a bearer token. No special token minting is required. The gateway serves the MCP protocol and the LLM proxy on the same hostname, so the MCP URL and the bearer token are the setup surface you hand to the client.

Transport contract​

The current hosted MCP surface uses streamable HTTP:

  • POST /mcp for client-to-server JSON-RPC requests such as initialize, tools/list, tools/call, resources/list, resources/read, and ping
  • GET /mcp for the server-sent events stream used for server-to-client notifications

The route is only valid on a published hostname. Requests that hit /mcp without publication context fail closed with a publication-required error.

Authentication​

Authenticate with an active Access Key or Gateway Key as a bearer token. These are filtered views of the shared API-token system and are managed on the console's API Tokens page.

This is not a localhost or unpublished-gateway exercise. You can only complete the client setup against a real published hostname, and your bearer token must have access to that publication surface.

Current capability scope​

The published gateway exposes a governed MCP bundle:

SurfaceCurrent behavior
History and audithistory_search, events_query, request_trace_get, history://sessions, and history://session/{id} expose traceable operational history
Discovery and guidancedocs_search, docs://index, docs://page/{id}, model and provider catalog tools, pricing, and telemetry resources help agents inspect the live gateway surface
Regions and gateway stateregions_list, region_get, gateway://effective-config, gateway://tool-servers, regions://catalog, and regions://organization expose locality and governed runtime state
Context fabricsession_init, context_search, context_share, context_recent, schema_lookup, plus context://team, context://branch/{name}, context://schema/{table}, and context://recent support shared engineering context
Governancepolicy_lint, policy_test, tool_servers_list, tool_server_get, and tool_server_validate expose Keeptrusts-specific governance workflows

tools/list and resources/list are authoritative for the capabilities available on a particular published gateway version.

Boundary with gateway MCP routing​

Do not confuse the hosted Keeptrusts MCP surface with the gateway's native MCP bridge config:

SurfacePurpose
Published hostname /mcpExpose Keeptrusts itself as a gateway-hosted MCP surface
providers.targets[].mcpRoute gateway traffic to an external MCP backend
tool_serversDeclare config-managed tool-server metadata for validation and discovery

Connection snippets​

Every MCP client needs the same two ingredients: the gateway's published agent hostname (for example your-agent.example.com) and your Access Key as a bearer token. Replace <your-published-hostname> with the resolved hostname and make KEEPTRUSTS_API_TOKEN available to your MCP client environment.

Codex CLI​

Register the streamable HTTP server and tell Codex which environment variable contains the bearer token:

codex mcp add keeptrusts \
  --url "https://<your-published-hostname>/mcp" \
  --bearer-token-env-var KEEPTRUSTS_API_TOKEN

Cursor​

Add to .cursor/mcp.json in your project or global Cursor config:

{
  "mcpServers": {
    "keeptrusts": {
      "url": "https://<your-published-hostname>/mcp",
      "headers": {
        "Authorization": "Bearer ${env:KEEPTRUSTS_API_TOKEN}"
      }
    }
  }
}

Claude Code​

Register via the CLI:

claude mcp add \
  --transport http \
  --header "Authorization: Bearer ${KEEPTRUSTS_API_TOKEN}" \
  keeptrusts "https://<your-published-hostname>/mcp"

Optional repository installer​

If you have a Keeptrusts repository checkout containing scripts/install-mcp.sh, the script can configure detected Cursor, Claude Code, Codex CLI, OpenCode, and VS Code clients. Preview its changes first:

export KEEPTRUSTS_API_TOKEN="kt_ak_..."
./scripts/install-mcp.sh \
  --dry-run \
  --hostname "<your-published-hostname>"

The script prints the MCP URL, credential environment variable, project directory, and per-assistant configuration summary.

After reviewing the target files and token-variable name, rerun without --dry-run. The script is optional; normal customers can use the manual client configuration without a repository checkout.

Next steps​