MCP Technical Reference
MCP Technical Reference
Strict protocol reference for implementers. No marketing — just specification, endpoints, and conformance details.
Transport
MCP gateway speaks JSON-RPC 2.0 over Streamable HTTP, per MCP spec 2025-11-25.
- Endpoint pattern
- https://trusteed.xyz/{storeSlug}/mcp
- Public demo store
- https://trusteed.xyz/demo-store/mcp
- Method
- POST application/json (JSON-RPC); GET → 405 Method Not Allowed
- Origin/Host validation
- Enabled (DNS rebinding protection per MCP §3.4)
- Protocol version header
- MCP-Protocol-Version: 2025-11-25
- Streaming
- SSE for tool/streaming responses; chunked transfer-encoding for long ops
Authentication
OAuth 2.1 Authorization Code with PKCE S256. RFC 8707 audience binding mandatory for write tools.
- Audience (resource indicator)
- https://api.trusteed.xyz
- Issuer
- https://auth.trusteed.xyz/
- JWKS URI
- https://auth.trusteed.xyz/.well-known/jwks.json
- Algorithms
- RS256 (RSA) with kid rotation
- Token TTL
- access 1h, refresh 30d (rotated)
- WWW-Authenticate (401)
- Bearer realm="MCP", resource_metadata="https://api.trusteed.xyz/.well-known/oauth-protected-resource"
Discovery endpoints
Standard well-known files for autonomous client configuration.
- /.well-known/oauth-protected-resource
- RFC 9728 — protected resource metadata
- /.well-known/oauth-authorization-server
- RFC 8414 — authorization server metadata
- /.well-known/mcp.json
- MCP server card (capabilities, tools, transport)
- /.well-known/acp.json
- Agent Commerce Protocol discovery
- /.well-known/security.txt
- RFC 9116 — security contact
- /llms.txt
- Site index for LLM crawlers
- /llms-full.txt
- Expanded LLM index with full content
OAuth scopes
Tokens carry one or more scopes. Tools enforce required scope server-side.
- mcp:read
- Read-only product/merchant discovery. Public access permitted on demo store.
- mcp:search
- Wildcard search and NLWeb queries.
- mcp:write
- Cart and checkout mutations (create_cart, select_shipping_option).
- mcp:checkout
- Settlement of orders (complete_checkout, ucp_complete_checkout).
- mcp:admin
- Tenant administration (rotate keys, manage agents).
Rate limits
Per-tier limits enforced at the gateway. 429 with Retry-After (seconds) on excess.
STARTER20 req/min per agent keyDemo + low-traffic prototypes
GROWTH200 req/min per agent keyProduction agents at scale
PRO500 req/min + analyticsMulti-merchant orchestrators
ENTERPRISECustomDedicated capacity, MCAP consent
Tool catalog
Full tool inventory with scopes, side effects, and tier requirements is documented separately.
View tool governance matrix →Error model
All errors follow stable JSON envelopes. Build retry logic against the error code, not the message.
View error reference →