Skip to main content

Gateway MCP surface

Prerequisites​

You must have:

  • 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, configure the client to open https://<your-published-hostname>/mcp. A localhost gateway or an unpublished agent does not satisfy this surface.

This is a different surface from:

  • provider: mcp in gateway config, which routes gateway traffic to an external MCP backend
  • tool_servers, which records inspection metadata but does not start or call a tool server

Active connection shape​

Use a published agent hostname in the form:

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

Use your Access Key or Gateway Key as a bearer token. You do not have to create a special token. The gateway supports the MCP protocol and LLM proxy on the same hostname. Give the MCP URL and bearer token to the client.

Transport contract​

The 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 correct only on a published hostname. An /mcp request without publication context fails closed with an mcp_publication_required error.

Authentication​

Authenticate with an active Access Key or Gateway Key as a bearer token. The shared API-token system supplies these keys as filtered views. Manage them on the console's API Tokens page.

You cannot complete this setup on localhost or an unpublished gateway. Use an active published hostname. Your bearer token must have access to that publication surface.

Active capability scope​

The published gateway exposes a governed MCP bundle:

SurfaceActive behavior
History and audithistory_search, events_query, request_trace_get, history://sessions, and history://session/{id} expose a traceable history of operations.
Discovery and guidancedocs_search, docs://index, docs://page/{id}, catalog tools, pricing, and telemetry resources help agents examine the live gateway.
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, and schema_lookup support shared engineering context. Related context resources give team, branch, schema, and recent context.
Governancepolicy_lint, policy_test, tool_servers_list, tool_server_get, and tool_server_validate expose Verdictan governance workflows.

Remote policy_lint accepts only bounded inline YAML (yaml, maximum 1 MiB). It does not accept filesystem paths. If you must lint a policy file on disk, use the local CLI command verdictan policy lint --file <path>.

For remote policy_test calls, use inline yaml. A pack_dir value refers to the filesystem of the published gateway process. It does not refer to a path on the MCP client.

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

Boundary with gateway MCP routing​

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

SurfacePurpose
Published hostname /mcpExpose Verdictan itself as a gateway-hosted MCP surface
providers.targets[].mcpRoute gateway traffic to an external MCP backend
tool_serversRecord inspection metadata. These declarations do not start or call tool servers.

Connection snippets​

Each MCP client must have two items. The first item is the published agent hostname, such as your-agent.example.com. The second item is your Access Key as a bearer token. Replace <your-published-hostname> with the resolved hostname. Make VERDICTAN_MCP_TOKEN available to your MCP client environment. Do not use the gateway runtime token for an MCP client.

Codex CLI​

Register the streamable HTTP server. In the same command, configure the environment variable that contains the bearer token:

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

Cursor​

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

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

Optional repository installer​

If your Verdictan repository checkout contains docker/install-mcp.sh, the script writes project configuration for Cursor, VS Code, and OpenCode. It does not detect installed clients. It does not configure Claude Code or Codex CLI. Always specify the MCP token variable:

export VERDICTAN_MCP_TOKEN="vdt_ak_..."
./docker/install-mcp.sh \
  --dry-run \
  --hostname "<your-published-hostname>" \
  --token-env VERDICTAN_MCP_TOKEN

The dry run lists the target paths. Without --dry-run, the script replaces .cursor/mcp.json, .vscode/mcp.json, and opencode.json in the selected project directory. It does not merge existing configuration. Review those files before you run the script. You can manually configure the client without a repository checkout.

Next steps​