MCP discovery

The Shroud gateway exposes a public discovery endpoint that describes the MCP and JSON-RPC surfaces, the auth scheme, the shipped tool catalogue with per-tool CU costs, and the server-level capabilities. Hosts and SDKs use it to wire up a client without hard-coding tool names or pricing.

This page is the protocol reference for the discovery contract itself — the response schema, the session lifecycle, the telemetry headers the gateway recognises, and how each piece relates to the wider MCP ecosystem. For the per-tool catalogue with input schemas, see MCP API. For host wiring recipes, see Connect an MCP client.

Overview

GET /.well-known/mcp returns a single JSON document with everything an MCP-aware host needs to bootstrap against Shroud: where to send MCP requests, where the JSON-RPC fallback lives, which Bearer header carries the API key, the live tool catalogue filtered by capability, and the server-wide capabilities flag set.

The endpoint exists so hosts and SDKs do not have to bake tool names, CU costs, or endpoint paths into their own code. A client can fetch the document at startup, render the catalogue, and stay in sync with the deployment without a release.

Endpoint

GET /.well-known/mcp

The endpoint is public and requires no authentication. The response is JSON (Content-Type: application/json).

curl https://shroud.us/.well-known/mcp

Only GET is allowed; other methods return 405 Method Not Allowed.

Response schema

{
  "name": "shroud",
  "version": "0.2.0",
  "description": "Shroud MCP Gateway — Midnight blockchain tools for AI agents",
  "mcpEndpoint": "/mcp",
  "rpcEndpoint": "/rpc",
  "auth": {
    "type": "bearer",
    "header": "Authorization"
  },
  "tools": [
    {
      "name": "midnight_getBlock",
      "description": "Get a Midnight block by height or hash",
      "estimatedCUMilli": 1000,
      "estimatedCUVaries": false
    }
  ],
  "capabilities": ["tools", "batch", "agent-tracking"]
}

Top-level fields

Field	Type	Description
`name`	string	Stable server identifier; always `"shroud"`.
`version`	string	Gateway version reported to clients (e.g. `"0.2.0"`).
`description`	string	Human-readable summary of what the gateway exposes.
`mcpEndpoint`	string	Path to the streamable-HTTP MCP endpoint, relative to the deployment origin.
`rpcEndpoint`	string	Path to the JSON-RPC 2.0 endpoint, relative to the deployment origin.
`auth`	object	Authentication scheme — see Auth.
`tools`	array	Per-tool catalogue — see Tools.
`capabilities`	string[]	Server-wide capability flags — see Capabilities.

Auth object

Field	Type	Description
`type`	string	Authentication scheme. Currently always `"bearer"`.
`header`	string	HTTP header carrying the credential. Currently always `"Authorization"`.

The Bearer token format is Bearer shroud_<env>_<random>. See Authentication for the prefix rules and key issuance flow.

Tools array

Each entry describes a single registered tool.

Field	Type	Description
`name`	string	Fully qualified tool name (`{skill}_{method}`, e.g. `midnight_getBlock`).
`description`	string	Human-readable summary copied from the skill registration. Includes a `[estimatedCUMilli: N]` marker.
`estimatedCUMilli`	integer	Pre-call CU estimate in milli-CU. Divide by 1000 for whole CU. Zero for tools whose cost is wholly determined at runtime.
`estimatedCUVaries`	boolean	`true` when the actual CU billed at call time may exceed the estimate (variable-cost tools such as `shroud_batch`). `false` for fixed-cost tools.

The tools array is filtered by capability — see Capability filtering below.

Capabilities array

A list of server-wide capability flags set on the deployment. Typical values:

Flag	Meaning
`tools`	Server exposes the MCP `tools/list` and `tools/call` methods.
`batch`	Server registers the `shroud_batch` virtual tool for sequential multi-call execution.
`agent-tracking`	Server reads `X-Agent-*` telemetry headers and attributes them to usage records.

Session lifecycle

The MCP streamable-HTTP transport maintains a stateful session per client. The session ID is carried in the Mcp-Session-Id HTTP header on every request after the initial handshake.

Issuance. The session ID is issued by the server in the response to the MCP initialize call. The mcp-go server library generates the ID and attaches it to the initialize response; most MCP client libraries (including mcp-remote, @modelcontextprotocol/sdk, and langchain-mcp-adapters) read the header automatically and replay it on subsequent requests.
Refresh. Sessions stay valid as long as the client keeps using them; there is no fixed TTL on the gateway side. When the underlying server process restarts (deploys, rolling updates), in-memory session state is dropped and the next request with the old Mcp-Session-Id will be rejected.
Stale ID. A request with an unknown Mcp-Session-Id is rejected by the mcp-go library with HTTP 404 Not Found. The client must re-run initialize to acquire a fresh session ID and retry the original request. Most MCP SDKs handle this transparently by re-establishing the session on demand.
Hand-rolled clients should treat any 404 from the MCP endpoint as a session-lost signal: drop the cached session ID, send a new initialize, then retry the original request.

Capability filtering

The tools array in the discovery response — and the response to the MCP tools/list method — are filtered by the calling identity's capability set.

Anonymous callers (no Authorization header) see only tools registered with the CapRead capability. Read-only tools are safe to advertise without authentication: they leak no state and they're rate-limited per source IP regardless.
Authenticated callers see every tool their key is permitted to invoke. When the deployment ships its first CapWrite tool, authenticated discovery includes it; anonymous discovery hides it.

The filter is a UX convenience: it keeps anonymous catalogue listings free of tools the caller cannot use. The security boundary lives in the router — even if a client guesses a write-tool name, the call returns SHROUD_PERMISSION_DENIED until a sufficiently-capable key is presented.

Today every shipped tool is CapRead, so the anonymous and authenticated views are identical. The filtering machinery is in place for the first CapWrite tool to ship.

Telemetry headers

When an MCP host calls /mcp, the gateway reads a small set of optional headers prefixed X-Agent-* and attaches them to the usage record produced by the call. They are diagnostic and billing-attribution metadata — never used for authentication or rate limits.

Header	Description	Example
`X-Agent-Name`	Short identifier for the agent or host process.	`claude-desktop`
`X-Agent-Version`	Agent or host version string.	`1.4.2`
`X-Agent-Session-ID`	Caller-side session correlation ID. Distinct from the MCP `Mcp-Session-Id`.	`sess_abc123`
`X-Agent-Provider`	Vendor or platform of the host.	`anthropic`, `cursor`, `langchain`
`X-Agent-Capabilities`	Comma-separated capability hints from the host.	`tools,streaming`

The gateway uses these to:

Attribute usage by agent in workspace dashboards and per-key analytics so an operator can see which agent consumed which CU.
Correlate logs across the MCP request, the gateway middleware chain, and downstream skill invocations.
Surface in telemetry alongside the existing correlation_id, session_id, and request_id fields.

Most MCP hosts do not pass X-Agent-* headers automatically. Configure them explicitly via the host's --header flag (for mcp-remote-bridged stdio hosts) or the headers config field (for HTTP-native hosts like LangChain and the OpenAI Agents SDK). See Connect an MCP client for worked examples.

Relationship to standards

The discovery endpoint and session model converge on the emerging 2026 MCP standardisation efforts:

SEP-1649 (MCP Streamable HTTP transport) — codifies the Mcp-Session-Id header, the 404-on-stale-session behaviour, and the MCP-Protocol-Version negotiation. Shroud targets protocol version 2025-11-25, the version the gateway warns about when a peer presents a different one.
SEP-1960 (MCP discovery via well-known URI) — codifies GET /.well-known/mcp as the canonical discovery path and the response shape (name, endpoints, auth, tools, capabilities). The Shroud schema is a strict superset; the estimatedCUMilli and estimatedCUVaries fields are Shroud-specific extensions that other servers MAY ignore.

The shape is intentionally close to what's standardising so a client written against the SEPs interoperates with Shroud without bespoke handling beyond reading the optional extension fields.

MCP API — protocol reference (per-tool input schemas, envelopes, error codes).
Connect an MCP client — host wiring recipes for Claude Desktop, Cursor, Cline, LangChain, and the OpenAI Agents SDK.
JSON-RPC API — same tool surface for non-MCP callers.
Authentication — the Bearer token format the discovery payload references.

Last modified: 08 May 2026