Connect an MCP client

Shroud exposes a Model Context Protocol endpoint at https://shroud.us/mcp so an AI agent host can call Shroud tools — including confidential inference and Midnight blockchain queries — through the standard MCP tool-use interface.

This page covers wiring up the four most common MCP-aware hosts: Claude Desktop, Cursor, Cline (VS Code), and LangChain. The full protocol reference lives in MCP API; this page is the plug it in and go guide.

Before you start

Get an API key from the Dashboard or the Telegram Mini App. Use the shroud_prod_ prefix against https://shroud.us, or shroud_dev_ against https://dev.shroud.us.
Pick which transport mode your host supports. Claude Desktop, Cursor, and Cline historically launch MCP servers as stdio child processes; for those we use the mcp-remote bridge to expose Shroud's HTTP /mcp endpoint as stdio.
Hosts that support streamable HTTP MCP transport directly (LangChain via langchain-mcp-adapters, custom integrations) can point at https://shroud.us/mcp without a bridge.

Discovery — sanity-check the endpoint first

Before wiring up a client, confirm the endpoint is reachable and the tools are what you expect:

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

The response lists mcpEndpoint, the auth scheme, the tool catalogue, and the supported capabilities (tools, batch, agent-tracking). The endpoint is public and needs no auth.

Claude Desktop

Claude Desktop reads its MCP server list from a JSON config file:

OS	Path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

Add a shroud entry under mcpServers. The bridge launches mcp-remote via npx so no global install is needed.

{
  "mcpServers": {
    "shroud": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://shroud.us/mcp",
        "--header",
        "Authorization: Bearer shroud_prod_..."
      ]
    }
  }
}

Restart Claude Desktop. The Shroud tool catalogue appears in the tool picker; calling a tool routes the call through mcp-remote to the Shroud gateway, which authenticates the Bearer token and runs the tool.

For confidential inference from inside an agent flow (the agent calls a Cocoon SDK tool that performs E2E-encrypted inference), plumb the Cocoon SDK separately — see Confidential inference. The MCP path is plaintext to the gateway; it is convenient for routing and tool discovery, not the right surface when the agent must keep prompts end-to-end encrypted.

Cursor

Cursor uses the same JSON shape under ~/.cursor/mcp.json (per-user) or in workspace settings under .cursor/mcp.json:

{
  "mcpServers": {
    "shroud": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://shroud.us/mcp",
        "--header",
        "Authorization: Bearer shroud_prod_..."
      ]
    }
  }
}

After saving, reload Cursor (Cmd+Shift+P → Developer: Reload Window) and the tools surface in the agent's tool list. Cursor shows MCP servers under Settings → MCP with health status.

Cline (VS Code)

Cline is a VS Code agent extension that supports MCP servers through its settings UI or a config file at ~/.config/cline/mcp_settings.json (the path varies by OS — open Cline: Open MCP Settings from the command palette to find yours).

{
  "mcpServers": {
    "shroud": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://shroud.us/mcp",
        "--header",
        "Authorization: Bearer shroud_prod_..."
      ]
    }
  }
}

Reload the Cline panel. Tools appear with their estimated CU cost pulled from the /.well-known/mcp discovery payload.

LangChain (HTTP-native)

LangChain's langchain-mcp-adapters package speaks streamable HTTP MCP directly — no mcp-remote bridge needed.

pip install langchain-mcp-adapters langchain-openai

from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain_openai import ChatOpenAI

client = MultiServerMCPClient({
    "shroud": {
        "url": "https://shroud.us/mcp",
        "transport": "streamable_http",
        "headers": {
            "Authorization": "Bearer shroud_prod_...",
        },
    },
})

tools = await client.get_tools()

# Bind the tools to any LangChain-compatible LLM. The example uses
# Shroud's OpenAI-compatible chat-completions surface; see
# [Migrate from OpenAI](migrate-from-openai.md).
llm = ChatOpenAI(
    api_key="shroud_prod_...",
    base_url="https://shroud.us/v1",
    model="Qwen/Qwen3-32B",
).bind_tools(tools)

response = await llm.ainvoke([{"role": "user", "content": "What's the latest finalized Midnight block?"}])

The same pattern works with LangGraph agents — pass tools to create_react_agent or any other agent constructor.

OpenAI Agents SDK

The OpenAI Agents SDK supports remote HTTP MCP servers via MCPServerStreamableHttp:

from agents import Agent, Runner
from agents.mcp.server import MCPServerStreamableHttp

shroud_mcp = MCPServerStreamableHttp(
    name="shroud",
    params={
        "url": "https://shroud.us/mcp",
        "headers": {
            "Authorization": "Bearer shroud_prod_...",
        },
    },
)

agent = Agent(
    name="Midnight assistant",
    instructions="Use Shroud tools to answer questions about Midnight.",
    mcp_servers=[shroud_mcp],
)

result = await Runner.run(agent, input="What is the latest finalized block on Midnight?")
print(result.final_output)

Agent metadata headers

When an MCP host calls /mcp, optional headers help with correlation, rate-limit tracking, and analytics on the Shroud side:

Header	Description	Example
`X-Agent-Name`	Agent name	`claude-desktop`
`X-Agent-Version`	Agent version	`1.4.2`
`X-Agent-Provider`	Host vendor	`anthropic`, `cursor`, `langchain`
`X-Agent-Session-ID`	Session correlation id	`sess_abc123`
`X-Agent-Capabilities`	Comma-separated capability list	`tools,streaming`

Most hosts do not pass these automatically. Add them via the host's --header flags or the headers config field shown in the LangChain and OpenAI Agents SDK examples above. For the full schema and what the gateway uses each header for, see MCP discovery — Telemetry headers.

Sanity-checking from the host

After wiring up, the fastest check is to ask the agent to list its tools — a healthy connection shows the Shroud tool names. If the host instead reports an MCP error:

Authentication failed (401). The Bearer token is wrong, the environment prefix doesn't match the deployment (shroud_prod_… vs shroud_dev_…), or the key was revoked. See Getting started — 401.
Tool not found. The host called a tool that isn't registered. Run the discovery curl above to see the live catalogue.
mcp-remote exits immediately. The bridge can't reach the endpoint. Try the discovery curl directly on the same machine to rule out network or DNS issues.
Connection works but tools time out. Some hosts have short default timeouts; Cocoon-SDK-shaped tools can take several seconds. Increase the host's MCP timeout if available.

For deeper protocol-level debugging — error envelope shapes, capability flags, batch semantics — see MCP API and Error reference.

Production posture

Treat the MCP endpoint like any other API surface:

Scope keys to one agent per workspace if you can — that way one compromised host config rotates a single key, not your whole account.
Read _meta.usedCUMilli from the MCP response envelope to track cost per agent. See Production guide — Observability.
For confidentiality of agent-to-model traffic, prefer the Cocoon SDK inside the agent instead of going through MCP for inference; MCP through the gateway sees prompts in cleartext.

MCP API — protocol reference (tools, schemas, envelopes).
JSON-RPC API — same tool surface for non-MCP callers.
Confidential inference — when the agent must keep prompts E2E-encrypted.
Production guide — retry, idempotency, rate limits, error handling.

Last modified: 08 May 2026