MCP Server

Overview

Context provides a remote MCP server that exposes the entire marketplace (Query, Execute, and Discover) through the Model Context Protocol. Any agent that supports Streamable HTTP MCP servers can connect in under a minute. Six tools are available:

Tool	What it does
`context_query`	Run an agentic Q&A query against the marketplace. Quick jobs return a grounded answer; long jobs return a `jobId`
`context_query_start`	Start a complex query and return a `jobId` immediately
`context_query_poll`	Wait inside one MCP tool call until a query job completes, fails, or reaches the poll timeout
`context_query_status`	Check a query job’s current status once
`context_execute`	Call a specific marketplace tool method directly and get the structured result
`context_discover`	Search the marketplace for available tools before querying or executing

The MCP server wraps the same Query and Execute APIs that the TypeScript and Python SDKs use. Authentication is the same sk_live_... API key you already have.

Building a daily report, alert, or repeatable data pipeline? See Agent Data Routines for the progression from natural-language Query to evidence_only, dataUrl, pinned tools, and optional direct execution.

Prerequisites

Before connecting, complete setup at ctxprotocol.com:

Creates your embedded wallet

Set spending cap

Approve USDC spending on the ContextRouter (one-time)

Fund wallet

Add USDC for tool execution fees

Generate API key

Settings → API Keys → Create key starting with sk_live_

Endpoint

https://www.ctxprotocol.com/api/mcp

Transport: Streamable HTTP (the standard for remote MCP servers). Authentication: Authorization: Bearer sk_live_... header on every request.

Setup by Agent

Cursor

Add to your project’s .cursor/mcp.json (or your global MCP settings):

{
  "mcpServers": {
    "ctxprotocol": {
      "url": "https://www.ctxprotocol.com/api/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_YOUR_KEY"
      }
    }
  }
}

Restart Cursor. The six tools appear in your MCP tool list automatically. If context_query_poll is missing after a deploy, refresh or restart the MCP server before testing long jobs.

Claude Code

claude mcp add --transport http ctxprotocol https://www.ctxprotocol.com/api/mcp \
  --header "Authorization: Bearer sk_live_YOUR_KEY"

OpenClaw / Claw Code

Add to your project’s mcp.json or pass via CLI:

{
  "mcpServers": {
    "ctxprotocol": {
      "transport": "streamable-http",
      "url": "https://www.ctxprotocol.com/api/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_YOUR_KEY"
      }
    }
  }
}

Any MCP Client (Generic)

Any client that supports Streamable HTTP transport can connect by pointing to:

URL: https://www.ctxprotocol.com/api/mcp
Transport: Streamable HTTP
Auth header: Authorization: Bearer sk_live_YOUR_KEY

The server returns a Mcp-Session-Id header after initialization. Clients that support session persistence should send it back on subsequent requests.

Tools Reference

context_query

Ask a natural-language question and get a grounded answer powered by the full marketplace.

Parameter	Type	Required	Description
`question`	string	Yes	The question to answer (1–4000 chars)
`agentModelId`	string	No	Advanced: choose the main librarian agent model. Omit for the platform default
`confirmAgentModelOverride`	boolean	No	Required when `agentModelId` is set. Confirms the model override was explicitly requested by the user
`responseShape`	string	No	`answer_with_evidence` (default) or `evidence_only`. See Answer vs evidence
`toolIds`	string[]	No	Restrict query to specific tool UUIDs (Manual Mode). Omit for Auto Mode discovery and selection
`favoritesOnly`	boolean	No	Override the account-level Favorites-Only Auto Mode for this request
`includeData`	boolean	No	Include bounded execution data inline. Large payloads return a preview plus full-data references
`includeDataUrl`	boolean	No	Persist the full execution data and return a URL, keeping large payloads out of your context window. Defaults to true in the ctxprotocol MCP tool
`includeDeveloperTrace`	boolean	No	Include a machine-readable runtime trace (tool selection, retries, loops) for debugging

Omit agentModelId for the platform-default librarian model. If a user explicitly wants a different Context librarian model, pass a supported agentModelId and set confirmAgentModelOverride: true. Calls that include agentModelId without confirmation fail fast so host LLMs do not accidentally leak their own model name into the librarian runtime.

Example prompt to your agent:

Use the context_query tool to answer: “What are the top Polymarket markets by volume right now?”

The response includes the answer text, structured evidence, and metadata. For long jobs, context_query may return a jobId before the answer is ready. Call context_query_poll with that exact jobId; do not call context_query again for the same question unless you want to start a duplicate paid query.

If the API key owner enables Favorites-Only Auto Mode in Settings, context_query and context_discover inherit that account default automatically. Pass favoritesOnly: true or favoritesOnly: false on a single MCP call to override it. If you pass explicit toolIds to context_query, manual tool selection wins and favorites filtering is ignored.

Auto Mode vs Manual Mode

context_query is the default one-call product surface:

Auto Mode: omit toolIds. The runtime runs marketplace discovery, selects tools with its managed selector, executes the librarian loop, and returns grounded output.
Named-provider Auto Mode: if a normal natural-language question names providers or venues, keep those names in the question text and still omit toolIds. For example, “using Crypto Positioning and Crypto Data” should usually stay Auto Mode unless the user explicitly asks to pin tools.
Manual Mode: pass toolIds from context_discover only when you explicitly want to pin/inspect tools or bypass broad marketplace selection. The runtime skips broad marketplace selection and runs the same librarian loop using only those tools.
Agent-driven mode: use context_discover + context_execute only when your host agent wants to drive exact method calls and synthesis itself.

For natural-language questions, start with context_query and answer from that result. It already performed managed discovery, selection, execution, grounding, and chart/artifact generation. Avoid context_discover, artifact fetching, or a follow-up context_execute verification pass unless you need raw method output, exact rows, or explicitly pinned tools.

Async Query Jobs

Some marketplace questions are slow: multi-tool analysis, chart generation, long historical windows, large data exports, and code-interpreter post-processing can exceed an MCP host’s direct tool-call window. Context handles this with durable query jobs: the backend librarian runtime keeps running discovery, tool calls, Python/code-interpreter work, chart generation, grounding, and synthesis after the initial MCP call returns a jobId. This is the same managed Query runtime, not a lightweight background fetch. The jobId is just the handle your MCP client uses while Context continues the long-running work server-side.

Tool	When to use	Next step
`context_query`	Default natural-language workflow	If it returns an answer, use it. If it returns `jobId`, call `context_query_poll`
`context_query_start`	You know the job is complex and want a handle immediately	Call `context_query_poll`
`context_query_poll`	You have a `jobId` and want the final result in one agent turn	Waits internally until `completed`, `failed`, or timeout
`context_query_status`	You need one cheap status check for UI/logging	Read status once; do not loop this manually from an LLM agent

context_query_poll blocks for up to 9 minutes by default (timeoutMs, raisable to 25 minutes if your MCP client tolerates long tool calls) and checks job status server-side every 5 seconds (intervalMs — this internal cadence costs no host-model tokens, so there is no reason to slow it down). While blocking, the server emits MCP progress notifications so progress-aware clients keep the call alive. If it returns a still-running status, call it again with the same jobId. Every query path — sync, async jobs, and MCP — shares the same 1800-second hosted compute ceiling.

Do not start another context_query for the same prompt after receiving a jobId. That creates a second paid query. Use context_query_poll instead.

For Cursor and other LLM agents, keep the loop simple: one context_query or context_query_start, then context_query_poll. Manual context_query_status loops are expensive because every check can consume another full model turn. If the poll tool is not visible in your MCP tool list, refresh/restart the MCP server rather than falling back to file searches or shell polling.

Answer vs evidence

responseShape controls whether Context adds a prose synthesis layer on top of the grounded result. Both shapes run the same managed runtime (discover, select, execute, ground); they differ only in what comes back.

Shape	Returns	Use when
`answer_with_evidence` (default)	A written answer plus structured `evidence`, `summary`, `artifacts`, `freshness`, `confidence`, and `usage`	You want a ready-to-read answer, or chat-parity output
`evidence_only`	Bounded `evidence`, optional bounded `data`, `computedArtifacts`, and full-data references with no prose	Your own agent (Cursor, Claude Code) is the synthesizer and wants grounded facts plus artifact/data handles

For evidence_only, unbounded raw data is not returned inline by default. Use the default evidence envelope and computedArtifacts inline, then fetch the full dataset from dataUrl/artifacts.canonicalDataRef when needed. If you set includeData: true, large payloads are still capped and returned as a truncation preview.

The full machine-readable payload is always in the MCP structuredContent field. The text content mirrors it, so hosts that only forward text still receive the evidence. If the response includes chart artifacts, the text content also includes markdown image links so agents can surface the charts to users.

For recurring agent-written reports, use responseShape: "evidence_only" with includeDataUrl: true. Let the host agent read the bounded evidence first, then fetch dataUrl only when it needs full rows for local computation.

For routine recipe capture, read toolsUsed from the terminal structured result before fetching raw data. Direct context_query returns it at structuredContent.toolsUsed; completed context_query_poll or context_query_status returns it at structuredContent.result.toolsUsed. Text-only hosts should show “Routine recipe tool candidates from toolsUsed”.

Large dataUrl files should be fetched with the SDK, Node/Python fetch, curl, or another real HTTP client. Browser-style webpage fetchers and summarizers may truncate multi-MB JSON.

Ambiguity And Capability Misses

When a request is ambiguous, the runtime answers with its best grounded assumption rather than blocking and may include assumptionMade in structuredContent. If no marketplace tool can satisfy the request, the response uses outcomeType: "capability_miss" with a typed capabilityMiss payload and suggested rewrites.

context_execute

Call a specific tool method with explicit arguments. Useful when your agent already knows which tool it wants. Use context_discover with mode: "execute" before calling context_execute. Methods surfaced by context_query grounding or query-mode discovery are not necessarily direct-execute eligible.

Parameter	Type	Required	Description
`toolId`	string (UUID)	Yes	The marketplace tool ID
`toolName`	string	Yes	The method name to call
`args`	object	No	Arguments for the method
`sessionId`	string (UUID)	No	Execution session for spend tracking
`maxSpendUsd`	string	No	Cap spend for this session
`closeSession`	boolean	No	Close the execution session after this call

context_discover

Search the marketplace to find tools before querying or executing. context_discover is free marketplace retrieval. It returns tool IDs plus mcpTools method metadata, but it does not run the managed selector used by context_query Auto Mode. Use it for catalog inspection, Manual Mode pinning, or direct execution prep. Do not call it first for a normal question just because the question mentions a provider name.

Parameter	Type	Required	Description
`query`	string	No	Search term
`limit`	number	No	Max results (1–20, default 10)
`mode`	`"query"` \| `"execute"`	No	Filter by mode
`favoritesOnly`	boolean	No	Override the account-level Favorites-Only Auto Mode for this request

Example Workflows

Simple Q&A (Auto Mode)

Tell your agent:

Use context_query to find out which Kalshi markets have the highest open interest today.

The runtime discovers relevant tools, handles execution end-to-end, and returns a complete answer.

Pinned Tools (Manual Mode)

For more control, first call context_discover, choose the relevant tool IDs, then call context_query with toolIds. Context still handles execution, grounding, and response assembly, but it stays within your pinned tool shortlist. Use this only when pinning is intentional. If the user simply asks “using Crypto Positioning and Crypto Data” as part of a natural-language analysis request, put that provider constraint in the question and keep Auto Mode.

Recurring Agent Routine

For daily reports, alerts, and repeated analyst jobs:

Start with Auto Mode context_query to find a good question shape.
Capture a Routine Recipe from the terminal structured result, including the exact question, assumptions, and toolsUsed names and IDs. Do not fetch dataUrl just to find tool IDs.
Switch to responseShape: "evidence_only" and includeDataUrl: true when your host agent writes the report.
Pin saved toolsUsed IDs as toolIds in context_query when the routine should stay within the same tool shortlist.
Use context_execute only if context_discover with mode: "execute" returns an eligible method.

See Agent Data Routines for a copy-paste routine prompt. TypeScript users can adapt the runnable SDK example at examples/client/src/agent-routine.ts in the examples/client package. For Crypto Data order-flow routines, it is normal for Execute discovery to return no eligible methods. In that case, keep the routine on pinned Query with responseShape: "evidence_only" and includeDataUrl: true.

Discovery -> Execute (agent-driven loop)

For full control, your agent can:

Call context_discover with a search query
Inspect the returned tools and methods
Call context_execute with the chosen tool and arguments
Synthesize the structured result into an answer

This mirrors the Agentic Pattern but through MCP instead of the SDK.

Pricing

MCP requests use the same pricing as the SDK:

Query: pay-per-response (selector model + agent model + invoked tool costs)
Execute: pay-per-call (method-level pricing set by tool builders)
Discover: free

Your wallet balance and spending cap apply identically.

Troubleshooting

401 Unauthorized

Ensure your Authorization header uses the format Bearer sk_live_.... Keys are generated at ctxprotocol.com/settings.

Tools not appearing in Cursor

Check that mcp.json is valid JSON and the url field points to https://www.ctxprotocol.com/api/mcp. Restart Cursor after saving.

Session expired

Sessions expire after 30 minutes of inactivity. Your MCP client will re-initialize automatically on the next request.

Query returns capability_miss

No marketplace tool can satisfy the request. Rephrase to target a supported venue or capability, or check the suggested rewrites in the response.

Overview

Why Context

Get Started

Build a Tool

Use the SDK

Earn Grants

Architecture

Overview

Prerequisites

Endpoint

Setup by Agent

Cursor

Claude Code

OpenClaw / Claw Code

Any MCP Client (Generic)

Tools Reference

context_query

Auto Mode vs Manual Mode

Async Query Jobs

Answer vs evidence

Ambiguity And Capability Misses

context_execute

context_discover

Example Workflows

Simple Q&A (Auto Mode)

Pinned Tools (Manual Mode)

Recurring Agent Routine

Discovery -> Execute (agent-driven loop)

Pricing

Troubleshooting

​Overview

​Prerequisites

​Endpoint

​Setup by Agent

​Cursor

​Claude Code

​OpenClaw / Claw Code

​Any MCP Client (Generic)

​Tools Reference

​context_query

​Auto Mode vs Manual Mode

​Async Query Jobs

​Answer vs evidence

​Ambiguity And Capability Misses

​context_execute

​context_discover

​Example Workflows

​Simple Q&A (Auto Mode)

​Pinned Tools (Manual Mode)

​Recurring Agent Routine

​Discovery -> Execute (agent-driven loop)

​Pricing

​Troubleshooting

Overview

Prerequisites

Endpoint

Setup by Agent

Cursor

Claude Code

OpenClaw / Claw Code

Any MCP Client (Generic)

Tools Reference

context_query

Auto Mode vs Manual Mode

Async Query Jobs

Answer vs evidence

Ambiguity And Capability Misses

context_execute

context_discover

Example Workflows

Simple Q&A (Auto Mode)

Pinned Tools (Manual Mode)

Recurring Agent Routine

Discovery -> Execute (agent-driven loop)

Pricing

Troubleshooting