Architecture

This page describes how the Cryptohopper Market Data MCP is structured internally, how requests flow through the system, and what guarantees it makes about data freshness and availability.

For the conceptual introduction, see What is MCP?

Component overview

The Cryptohopper MCP is composed of four layers:

1. Protocol layer: Implements the MCP specification — tool discovery, invocation, streaming responses.
2. Auth and quota layer: Validates bearer tokens, enforces tier access, counts calls against weekly limits.
3. Data aggregation layer: Queries upstream exchanges, normalises responses into a common schema.
4. Exchange connectors: Per-exchange adapters that translate between exchange-native APIs and the internal schema.

A request from an MCP client flows through all four layers in order.

Request flow

A typical tool invocation proceeds as follows:

1. Client sends request. The MCP client sends a JSON-RPC request over the SSE stream, containing the tool name and arguments.
2. Protocol layer validates. The request is checked against the tool's JSON schema. Malformed requests return INVALID_PARAMETER or MISSING_PARAMETER.
3. Auth layer validates token. The bearer token is resolved to an account. Invalid or revoked tokens return UNAUTHORIZED.
4. Quota layer checks limits. The call is counted against the account's weekly quota and short-interval rate limit. Exceeding either limit returns QUOTA_EXCEEDED or RATE_LIMIT_EXCEEDED.
5. Tier check. The requested exchange and — for candle queries — the lookback depth are validated against the tier's allow list. Violations return EXCHANGE_NOT_SUPPORTED or HISTORY_LIMIT_EXCEEDED.
6. Aggregation layer dispatches. The request is routed to the appropriate exchange connector.
7. Connector queries upstream. The connector makes the corresponding call to the upstream exchange API.
8. Response normalises. The upstream response is mapped to the internal schema and returned to the client through the SSE stream.

Each of these steps can terminate the request with an error. Error semantics are described in error reference.

Transport

The MCP uses HTTP with Server-Sent Events (SSE):

• Initial connection and authentication: a standard HTTP request.
• Ongoing tool invocations: a bidirectional JSON-RPC flow over SSE.

The choice of SSE is part of the MCP specification. It supports streaming responses and long-lived connections without the overhead of bespoke websocket handshakes.

The service endpoint is https://mcp-data.cryptohopper.com/mcp. All traffic is TLS-encrypted.

Statelessness

The MCP server does not hold session state between requests. Each tool invocation is independent:

• No server-side cursor or iterator.
• No per-session cache.
• No implicit context carried between calls.

State that needs to persist across calls is the client's responsibility. In agent workflows, the model holds state in its own context window.

Data freshness

Each data type has a different freshness profile:

Data type	Source	Freshness
Ticker	Upstream exchange	Near real-time, refreshed on each invocation
Orderbook	Upstream exchange	Snapshot at request time; no streaming updates
Current candle	Upstream exchange	Current bar reflects latest trades
Historical candle	Upstream exchange + cache	Immutable once the candle has closed

Ticker and orderbook calls always fetch from the upstream exchange. Historical candles may be served from cache when the bar has already closed, since closed bars are immutable.

Note: The MCP does not provide a pub/sub streaming mode. Each call is a point-in-time fetch.

Aggregation model

Each exchange connector implements the same internal interface but wraps the specific exchange's API. The aggregation layer:

• Normalises symbol formats. Exchanges use different pair notations (BTCUSDT vs BTC-USDT vs BTC/USDT); the MCP exposes a uniform BASE/QUOTE format.
• Harmonises field names. Exchange APIs differ in how they name bid, ask, last price, and volume fields; the MCP returns a common schema.
• Handles timezone and timestamp conventions. All timestamps in responses are UTC, ISO-8601 formatted.
• Filters to supported pairs. Non-spot markets (perpetuals, options) are excluded from MCP responses even if the upstream exchange offers them.

See data model for the full response schema.

Per-exchange differences

The MCP aims for a uniform output, but upstream exchange differences cannot always be fully hidden:

• Orderbook depth. Different exchanges expose different maximum depths. The MCP returns what the upstream exposes.
• Candle timeframes. Not every exchange supports every timeframe. Unsupported combinations return TIMEFRAME_NOT_SUPPORTED.
• Historical lookback. Exchanges vary in how far back they serve historical data. Requests within the MCP's tier limits may still fail if the upstream exchange does not serve that depth; this returns DATA_UNAVAILABLE.

Per-exchange capabilities are reflected in the response to the list-pairs and list-exchanges tools.

Upstream reliability

Upstream exchange APIs can be unavailable or slow. The MCP does not retry upstream calls on behalf of the client; a failing upstream returns EXCHANGE_UNAVAILABLE or DATA_UNAVAILABLE.

Clients are expected to retry transient errors after a brief delay. Well-behaved MCP clients do this automatically.

The MCP itself is designed for high availability, but depends on upstream exchange health for end-to-end reliability.

Concurrency

Multiple concurrent tool invocations from a single client are permitted. Each invocation is independent and counts separately against the quota. The rate limit applies across concurrent calls as well as sequential ones.

Clients that fan out many simultaneous requests should throttle to avoid hitting the rate limit.

Security boundary

The MCP server:

• Terminates TLS at the edge.
• Validates the bearer token on every request.
• Does not accept or act on credentials for any external exchange. All upstream exchange access uses the MCP's own credentials, configured server-side.
• Does not expose the upstream exchange's raw error messages to the client — errors are mapped to the MCP's own error codes.

Client-side keys are the only credential clients need to provide. See API key security best practices.

Versioning

The MCP protocol surface is versioned according to the MCP specification. Tool schemas may evolve over time:

• Additive changes (new tools, new optional arguments, new response fields) are non-breaking.
• Breaking changes (removed fields, changed argument types) are announced ahead of time.

Clients discover the current tool surface dynamically on connection, so additive changes take effect without client redeployment.