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/{storeSlug}/mcp"
Discovery endpoints
Standard well-known files for autonomous client configuration.
- /.well-known/oauth-protected-resource/{storeSlug}/mcp
- 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).
Rate limits
Per-tier limits on the agentic REST API. The MCP Gateway is a different layer: its keys carry no tier, so every plan gets 30 req/min there. 429 with Retry-After (seconds) on excess.
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 →