Skip to content

MCP Gateway

The MCP Gateway turns the tools your agents need into a governed, project-scoped Model Context Protocol (MCP) API. An external MCP client connects to the gateway with a project API key; the gateway decides who may reach what, holds upstream credentials server-side, and proxies the call without exposing the caller's token or the upstream secret.

View as Markdown Open the plain-text version of this page.

Note

This surface governs tool calls. It is a separate product from the AI Gateway, which governs model inference. MCP endpoint policies do not control local shell execution, browser automation, or scripts running inside the agent runtime; those stay with the agent and its host.

The streamable-HTTP ingress selects one target per connection through the required ?mcp=<id> query parameter: built-in hosted tools are reached at ?mcp=provon (trace and Finding readers) and ?mcp=duckduckgo (web search), while each registered federation server is reached at ?mcp=<serverId>. A client does not receive one merged catalog on a single URL; it connects to the target it needs, and access policy then decides which of that target's tools the caller may list or invoke.

Two surfaces, one project boundary#

Surface Purpose Endpoint Auth
Management routes Register servers, inspect the catalog, seal credentials, publish tools, and write policies /v1/projects/:projectId/mcp/servers and sibling management resources Bearer key with mcp:manage, or a Workbench session with project management permission
Tool gateway ingress The streamable-HTTP MCP protocol an external client speaks: discovery and invocation /v1?mcp=<id> on the hosted edge; /mcp/v1?mcp=<id> on the self-hosted Node runtime Project API key with mcp:invoke; sessions are rejected

Management writes shape the catalog; the tool gateway enforces the catalog and policy on every call. Full route contracts live in the MCP API reference.

Two tool origins#

  • Hosted tools are built-in, read-only capabilities with no upstream connection and no sealed secret. The registered allowlist itself defines what can appear; five hosted tools ship out of the box and are callable by a project principal with mcp:invoke without an explicit policy: search_traces, get_trace, list_findings, get_finding on the built-in provon target (?mcp=provon), and web_search on the built-in duckduckgo target (?mcp=duckduckgo).
  • Federation tools are proxied to an upstream you register. A server can be a native streamable- HTTP MCP server or a REST service imported from an OpenAPI document. Federation tools are default-deny: they stay hidden and uninvocable until published and explicitly allowed.

Publish state controls eligibility; principal policy controls visibility and invocation. The two are evaluated together, so a published federation tool with no matching allow policy stays hidden and uninvocable.

State In tools/list Through tools/call
draft No No
published Eligible; returned only to principals allowed by policy Eligible; succeeds only for authorized principals
deprecated Eligible with a deprecation notice; same policy rule Eligible; same policy rule
archived No No

The pre-approved hosted tools are the exception to default-deny: they list and run for any mcp:invoke caller unless an explicit deny matches. Federation tools require an allow policy on top of publish state. Imported OpenAPI operations land as draft tools and must be published before discovery. See Security for how publish state and principal policy compose.

Start here#

Goal Read
Register a server, publish a tool, and connect a first MCP client Quickstart
Learn the request lifecycle and runtime capability matrix Architecture
Authorize principals, seal credentials, and understand guardrail and audit behavior Security
Onboard a REST service from an OpenAPI document OpenAPI import
Drive management from a terminal MCP CLI
Isolate a failing management route, tool gateway call, or upstream Troubleshooting

Supported capabilities#

  • Project-scoped management of servers, tools, credentials, and access policies.
  • Streamable-HTTP MCP ingress with stateless JSON-RPC methods initialize, notifications/initialized, ping, tools/list, and tools/call; the required ?mcp= parameter selects a built-in target or a federation server id, and omitting it returns 400 MCP_ID_REQUIRED.
  • Outbound federation to remote streamable-HTTP MCP servers.
  • OpenAPI 3 documents normalized into tools; import, catalog sync, and invocation supported on both runtimes.
  • Sealed static-header upstream credentials, access policies, tool guardrail budgets, and audit attributes on tool calls.
  • A project-wide read-only catalog merging hosted and federation tools for the Workbench.

Runtime notes#

  • The hosted edge meters tool calls per project, principal, and tool. On a self-hosted Node process, the outbound federation bucket is per (server, tool) and hosted calls keep a separate per-process bucket; these buckets are not distributed across multiple Node processes. Scale-out deployments should rely on the hosted edge or on upstream provider-side quotas.
  • Unsupported or unwired capabilities return a clear 501 or error code rather than a silently approximated result; check Troubleshooting before assuming a feature gap.