# 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.

> [!NOTE]
> This surface governs **tool calls**. It is a separate product from the
> [AI Gateway](../ai-gateway/index.md), 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](../api/mcp.md).

## 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](./security.md) 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](./quickstart.md)           |
| Learn the request lifecycle and runtime capability matrix                           | [Architecture](./architecture.md)       |
| Authorize principals, seal credentials, and understand guardrail and audit behavior | [Security](./security.md)               |
| Onboard a REST service from an OpenAPI document                                     | [OpenAPI import](./openapi.md)          |
| Drive management from a terminal                                                    | [MCP CLI](../cli/mcp.md)                |
| Isolate a failing management route, tool gateway call, or upstream                  | [Troubleshooting](./troubleshooting.md) |

## 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](./troubleshooting.md) before assuming a feature gap.