Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.

MCP endpoint contract and @keeptrusts/agent 0.1.0 limit

:::danger Do not use the 0.1.0 MCP helpers

This unlisted page is retained to explain a version-specific incompatibility. For a supported setup, follow Gateway-Hosted MCP.

:::

Keeptrusts exposes MCP on an enabled agent publication at:

https://<published-hostname>/mcp

The route uses remote streamable HTTP. A client must send an MCP initialize request before methods such as tools/list and tools/call, preserve the returned session identifier when required, and authenticate with a Keeptrusts API token as a bearer token.

It is not a REST endpoint with a /tools child route.

Current Agent SDK mismatch​

@keeptrusts/agent 0.1.0 exports createMcpGatewayClient, buildMcpGatewayConfig, and getMcpTools, but they are not a protocol-compliant client for the published endpoint:

  • getMcpTools sends GET /tools instead of JSON-RPC tools/list;
  • no initialize exchange is performed;
  • no MCP session ID is captured or reused;
  • the builder appends /mcp to the SDK's default gateway URL, producing http://localhost:41002/v1/mcp, while the gateway route is /mcp at the host root;
  • the builder's headers object contains tracing headers but not the bearer authorization value needed by an external client.

Do not use these exports to validate hosted MCP or discover its tools.

Supported client path​

Configure a protocol-capable MCP client with:

  • the active publication URL ending exactly in /mcp;
  • remote streamable-HTTP transport;
  • an active Keeptrusts API token in Authorization: Bearer ...;
  • any client-specific bearer-token environment reference documented in Gateway-Hosted MCP.

Verify the connection with a successful initialize followed by a real tools/list exchange. A generic HTTP 200 check is not enough to prove an MCP session works.

Keep the gateway surfaces separate​

SurfacePurposeCredential
Published https://<host>/mcpMCP tools and resources for an external MCP clientKeeptrusts API token
Gateway model API under /v1OpenAI-compatible, Responses, Messages, and other configured model trafficGateway request token
providers.targets[].mcpGateway-side calls to an external MCP backendCredential required by that external backend

Configuring one surface does not configure either of the others.

Publication requirements​

The gateway returns a not-found response when its MCP server is disabled. The public route also requires an agent publication context and supports bearer authentication for the hosted MCP endpoint. Confirm the active publication URL before troubleshooting the client protocol.

Next steps​