MCP API

Shroud exposes a Model Context Protocol (MCP) endpoint for AI agent integration. MCP uses streamable HTTP transport for streaming communication.

Endpoint

POST /mcp

Authentication

Authorization: Bearer shroud_prod_...

Discovery

The discovery endpoint returns available tools, authentication requirements, and server capabilities:

GET /.well-known/mcp

Example response:

{
  "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"]
}

For the full discovery response schema and field-by-field semantics, see MCP discovery.

Available Tools

Tools are prefixed by skill name. Shipped tools are grouped below by skill (Midnight blockchain, Platform, Docs) plus a Meta section for the shroud_batch virtual tool.

Block & Chain Tools

Tool	Description	CU Cost
`midnight_getBlock`	Get block by height or hash	1.0
`midnight_getBlockDecoded`	Get block with decoded extrinsics and events	2.0
`midnight_getHealth`	Get Midnight node health status	0.1
`midnight_getNodeInfo`	Get node info (chain name, node name, version)	0.1
`midnight_getChainStats`	Get aggregated chain statistics	0.5

State & Storage Tools

Tool	Description	CU Cost
`midnight_getStorage`	Query runtime storage by key	0.2
`midnight_queryStorage`	Query storage for multiple keys	0.2 per key
`midnight_getAccount`	Get account info (balance, nonce)	0.5
`midnight_getEvents`	Get events from a block	1.5

RPC Tools

Tool	Description	CU Cost
`midnight_rpc`	Generic whitelisted RPC proxy call	1.0
`midnight_listMethods`	List available RPC methods	0.1

Platform Tools

Tool	Description	CU Cost
`platform_listModels`	List Cocoon inference models across networks with current per-token pricing in milli-CU.	0.1
`platform_getAttestationQuote`	Fetch a fresh TEE attestation quote (base64) plus the pre-computed image hash (hex SHA-256) from the Cocoon confidential compute environment.	0.1

Docs Tools

Tool	Description	CU Cost
`docs_search`	Search Shroud platform documentation; returns matching paragraphs with titles, URLs, and BM25 relevance scores.	0.1

Meta Tools

Tool	Description	CU Cost
`shroud_batch`	Execute multiple tool calls in a single request	0 base + sum of inner calls (varies)

Tool Input Schemas

midnight_getBlock

Parameter	Type	Required	Description
`height`	integer	One of `height` or `hash`	Block height
`hash`	string	One of `height` or `hash`	Block hash (hex, 0x-prefixed)

Request:

{
  "tool": "midnight_getBlock",
  "input": {
    "height": 100
  }
}

Response:

{
  "block": {
    "header": {
      "parentHash": "0x...",
      "number": "0x64",
      "stateRoot": "0x...",
      "extrinsicsRoot": "0x...",
      "digest": { "logs": ["0x..."] }
    },
    "extrinsics": ["0x..."]
  }
}

midnight_getBlockDecoded

Parameter	Type	Required	Description
`height`	integer	One of `height` or `hash`	Block height
`hash`	string	One of `height` or `hash`	Block hash (hex, 0x-prefixed)

Request:

{
  "tool": "midnight_getBlockDecoded",
  "input": {
    "height": 100
  }
}

Response:

{
  "block": { "header": { ... }, "extrinsics": ["0x..."] },
  "decodedExtrinsics": [
    {
      "index": 0,
      "pallet": "Timestamp",
      "method": "set",
      "args": "0x...",
      "isSigned": false,
      "raw": "0x..."
    }
  ]
}

midnight_getHealth

No parameters required.

Request:

{
  "tool": "midnight_getHealth",
  "input": {}
}

Response:

{
  "peers": 12,
  "isSyncing": false,
  "shouldHavePeers": true
}

midnight_getNodeInfo

No parameters required.

Request:

{
  "tool": "midnight_getNodeInfo",
  "input": {}
}

Response:

{
  "chain": "Midnight",
  "name": "midnight-node",
  "version": "1.0.0"
}

midnight_getChainStats

No parameters required.

Request:

{
  "tool": "midnight_getChainStats",
  "input": {}
}

Response:

{
  "chain": "Midnight",
  "chainType": "Live",
  "finalizedHash": "0x...",
  "finalizedNumber": 411363,
  "latestNumber": 411365,
  "health": { "peers": 12, "isSyncing": false, "shouldHavePeers": true },
  "properties": {
    "tokenDecimals": 8,
    "tokenSymbol": "NIGHT",
    "ss58Format": 42,
    "isEthereum": false
  }
}

midnight_getAccount

Parameter	Type	Required	Description
`address`	string	Yes	SS58-encoded account address
`blockHash`	string	No	Block hash to query at a specific block

Request:

{
  "tool": "midnight_getAccount",
  "input": {
    "address": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY"
  }
}

Response:

{
  "nonce": 42,
  "consumers": 1,
  "providers": 1,
  "sufficients": 0,
  "data": {
    "free": "1000000000000",
    "reserved": "0",
    "miscFrozen": "0",
    "feeFrozen": "0"
  }
}

midnight_getStorage

Parameter	Type	Required	Description
`key`	string	Yes	Hex-encoded storage key (0x-prefixed)
`blockHash`	string	No	Block hash to query at a specific block

Request:

{
  "tool": "midnight_getStorage",
  "input": {
    "key": "0x26aa394eea5630e07c48ae0c9558cef7"
  }
}

Response:

{
  "key": "0x26aa394eea5630e07c48ae0c9558cef7",
  "value": "0x..."
}

midnight_queryStorage

Parameter	Type	Required	Description
`keys`	string[]	Yes	Array of hex-encoded storage keys (max 100)
`blockHash`	string	No	Block hash to query at a specific block

Request:

{
  "tool": "midnight_queryStorage",
  "input": {
    "keys": ["0x26aa394eea5630e07c48ae0c9558cef7"]
  }
}

midnight_getEvents

Parameter	Type	Required	Description
`blockHash`	string	Yes	Block hash (hex, 0x-prefixed)

Request:

{
  "tool": "midnight_getEvents",
  "input": {
    "blockHash": "0xabc123..."
  }
}

Response:

[
  {
    "index": 0,
    "phase": "ApplyExtrinsic(0)",
    "pallet": "System",
    "event": "ExtrinsicSuccess",
    "data": "0x..."
  }
]

midnight_rpc

Parameter	Type	Required	Description
`method`	string	Yes	RPC method name (e.g. `chain_getFinalizedHead`). Must be whitelisted — see RPC Proxy.
`params`	array	No	Optional array of RPC params (default `[]`)

Request:

{
  "tool": "midnight_rpc",
  "input": {
    "method": "chain_getFinalizedHead",
    "params": []
  }
}

midnight_listMethods

Parameter	Type	Required	Description
`namespace`	string	No	Filter by prefix (e.g. `state`, `chain`)

Request:

{
  "tool": "midnight_listMethods",
  "input": {}
}

platform_listModels

Parameter	Type	Required	Description
`network`	string	No	Filter to a specific Cocoon network (`cocoon-classic`, `cocoon-alpha`). Omit for all networks.

Input schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "network": {
      "type": "string",
      "description": "Filter to a specific Cocoon network (e.g. cocoon-classic, cocoon-alpha). Omit for all networks."
    }
  },
  "additionalProperties": false
}

Request:

{
  "tool": "platform_listModels",
  "input": {}
}

Response is an array of model entries; each entry carries network, model_id, active_workers, and per-token milli-CU prices (prompt, completion, cached).

platform_getAttestationQuote

Parameter	Type	Required	Description
`report_data`	string	No	Optional 64-byte hex-encoded report data (128 hex chars) bound into the quote. Omit for image-only verification.

Input schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "report_data": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{128}$",
      "description": "Optional 64-byte hex-encoded report data to bind into the attestation quote. Omit for image-only verification."
    }
  },
  "additionalProperties": false
}

Returns the raw TEE attestation quote (base64) and a pre-computed image hash (hex SHA-256) for identity verification. See How attestation works for the verification flow.

docs_search

Parameter	Type	Required	Description
`query`	string	Yes	Search query string (non-empty).
`limit`	integer	No	Maximum number of results to return (1-25, default 10).

Input schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "Search query string"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 25,
      "default": 10,
      "description": "Maximum number of results to return (1-25, default 10)"
    }
  },
  "required": ["query"],
  "additionalProperties": false
}

Returns matching paragraphs with titles, URLs, and BM25 relevance scores against the embedded Shroud documentation index.

Agent Headers

Shroud recognizes optional agent metadata headers for tracking and analytics:

Header	Description	Example
`X-Agent-Name`	Agent name	`my-agent`
`X-Agent-Version`	Agent version	`1.0.0`
`X-Agent-Session-ID`	Session correlation ID	`sess_abc123`
`X-Agent-Provider`	Agent provider	`langchain`
`X-Agent-Capabilities`	Agent capabilities	`tools,streaming`

Batch Calls

Use shroud_batch to execute up to 20 sequential tool calls in a single request. Each call in the batch is executed independently with its own usage tracking.

{
  "tool": "shroud_batch",
  "input": {
    "calls": [
      {"tool": "midnight_getBlock", "params": {"height": 100}},
      {"tool": "midnight_getBlock", "params": {"height": 101}},
      {"tool": "midnight_getChainStats", "params": {}}
    ]
  }
}

Response contains results for each call:

[
  {"tool": "midnight_getBlock", "content": { ... }, "usedCUMilli": 1000},
  {"tool": "midnight_getBlock", "error": "block not found", "usedCUMilli": 0},
  {"tool": "midnight_getChainStats", "content": { ... }, "usedCUMilli": 500}
]

Usage Tracking

Every tool call reports credit unit (CU) consumption in response metadata:

{
  "content": [
    {
      "type": "text",
      "text": "{ ... }"
    }
  ],
  "_meta": {
    "usedCUMilli": 1000,
    "toolName": "midnight_getBlock",
    "timestamp": "2025-01-15T10:30:00Z",
    "latencyMs": 160,
    "genAIRequestModel": "",
    "genAIUsageInputTokens": 0,
    "genAIUsageOutputTokens": 0
  }
}

`_meta` fields

Field	Type	Description
`usedCUMilli`	integer	Credit units consumed by this call, in milli-CU. Divide by 1000 for whole CU.
`toolName`	string	Echo of the tool that was invoked.
`timestamp`	string (RFC 3339)	Server timestamp at which the response was produced.
`latencyMs`	integer	End-to-end server processing time in milliseconds.
`genAIRequestModel`	string	Model identifier used for the call. Populated for AI inference tools; empty string for non-inference tools like `midnight_getBlock`.
`genAIUsageInputTokens`	integer	Prompt token count reported by the inference worker. Zero for non-inference tools.
`genAIUsageOutputTokens`	integer	Completion token count reported by the inference worker. Zero for non-inference tools.

The three genAI* fields follow the OpenTelemetry GenAI semantic conventions and are present on every successful tool call response. They carry meaningful values only when the underlying tool runs an LLM; for purely RPC-shaped tools they are zero/empty so the response shape stays uniform.

Error Handling

MCP returns errors as a tool result with isError: true and a structured SHROUD code in _meta.errorCode:

{
  "content": [
    {
      "type": "text",
      "text": "tool not found: midnight_nonExistent"
    }
  ],
  "isError": true,
  "_meta": {
    "errorCode": "SHROUD_TOOL_NOT_FOUND"
  }
}

Error Code	Description
`SHROUD_INVALID_PARAMS`	Invalid or malformed tool parameters
`SHROUD_TOOL_NOT_FOUND`	Unknown tool name
`SHROUD_TOOL_EXECUTION_ERROR`	Tool invocation failed (e.g. upstream node error)
`SHROUD_BATCH_TOO_LARGE`	Batch exceeds 20 calls
`SHROUD_INTERNAL_ERROR`	Internal server error

Last modified: 08 May 2026

MCP API

Endpoint

Authentication

Discovery

Available Tools

Block & Chain Tools

State & Storage Tools

RPC Tools

Platform Tools

Docs Tools

Meta Tools

Tool Input Schemas

midnight_getBlock

midnight_getBlockDecoded

midnight_getHealth

midnight_getNodeInfo

midnight_getChainStats

midnight_getAccount

midnight_getStorage

midnight_queryStorage

midnight_getEvents

midnight_rpc

midnight_listMethods

platform_listModels

platform_getAttestationQuote

docs_search

Agent Headers

Batch Calls

Usage Tracking

_meta fields

Error Handling

`_meta` fields