Build & List Your Tool - Context Protocol

New to MCP? Start with our 5-Minute Quickstart to build and deploy your first server, then come back here for advanced features.

Overview

Want to earn revenue from your data? Turn the insights people pay $500/year for into $0.10/response revenue you keep. Build an MCP server and register it as an MCP Tool on the Context marketplace.

Start With A Product Contract

Before you write code, decide which product you are actually shipping:

Surface	What you are selling	What good looks like
Query	A premium answer contract	Context can return `answer_with_evidence` in chat and `evidence_only` for external agents with the right facts, source refs, freshness, confidence, and view hints
Execute	A normalized primitive contract	Agents get stable typed fields, consistent pagination/filtering, and explicit execute pricing without having to normalize fragmented APIs themselves
Both	A normalized primitive that can also power premium answers	The same canonical data can support Query synthesis and direct Execute calls

Every serious builder brief should specify:

the exact premium feature or normalized primitive
the target paying user
5 must-win prompts or requests
the expected evidence fields or normalized schema
the ideal output surface (Query, Execute, or both)
freshness / latency expectations
why free substitutes or direct APIs are insufficient

If your pitch still reads like a category label such as “crypto analytics” or “company data,” it is too vague. Name the exact feature users would pay for.

Optional Search Helpers For Search-Hard Venues

Most contributors should rely on strong upstream search plus clean tool schemas. If your venue’s native search is too weak to reliably resolve the right market, entity, or series from real user prompts, you may adopt the optional contributor-side pattern described in Optional Contributor Search Helpers. Treat that pattern as a contributor utility, not a marketplace requirement:

keep Context discovery generic
keep candidate gathering, normalization, provenance, and validation deterministic inside the contributor
inject any model judge behind a provider-agnostic boundary
keep provider credentials and model spend contributor-owned
return honest degraded outcomes when the judge is disabled, malformed, slow, unavailable, or over budget
keep the helper optional even after it ships in both SDKs; contributors with strong upstream search should still avoid it
save replayable validation artifacts for named regressions, generic overlap, still-ambiguous, and capability-miss cases before you recommend it more broadly

If your upstream venue already exposes reliable search and candidate selection, do not add this helper just because it exists. For the full adoption checklist, parity contract, and rollout gate, see Optional Contributor Search Helpers.

AI-Assisted Builder (TL;DR)

Have an API subscription you want to unbundle? Use Cursor, Claude, or any AI coding agent to build and optimize your MCP server automatically.

Prerequisite: You need Context7 MCP configured in your AI coding environment to fetch API documentation automatically.

Three-Step Workflow

Build the MCP Server

Use the MCP Builder Template as a system prompt to:

Fetch API docs via Context7 and discover all endpoints
Define the exact feature, target user, must-win prompts, evidence fields, and ideal surface before writing code
Design premium answer products or normalized primitives (not just API passthroughs)
Generate complete schemas with outputSchema
Implement the full MCP server

Use the mcp-builder-template.md with Context7 for [your-api-library-id].
Fetch the documentation and design tools that answer complex questions.

Go to ctxprotocol.com/contribute to register your tool. You’ll get a Tool ID and can generate an API key at Developer → API Keys. You’ll need both for the next step.

Optimize and Ship

Before you start: Make sure your wallet has a small balance (a few dollars is enough). The optimization process makes real query calls through the Context platform to validate your tool’s responses. If your wallet is empty, the librarian cannot complete the agentic flow and validation will fail. Deposit funds at Developer Dashboard.Load the MCP Tool Optimization Skill into your AI coding agent with your API key and Tool ID. The skill automatically:

Researches your vertical to find where your tool creates unique value
Generates tough, realistic test prompts and proves they beat free LLMs
Checks data quality from a buyer’s perspective
Audits latency metadata for correctness
Fixes issues and retests in a loop until everything passes
Generates the optimal marketplace description with proven suggestedPrompts
Pushes the description and clickable example questions directly to your listing via the SDK, with no manual copy-paste

Load the mcp-tool-optimization-skill.md from context-sdk/docs/.
My server code is in ./server.ts
My MCP endpoint is https://my-tool.example.com/mcp
My CONTEXT_API_KEY is sk_live_...
My TOOL_ID is abc-123-def
Run the full optimization workflow.

A tool that works is table stakes. A tool that delivers insights users cannot get from ChatGPT for free is what earns revenue and may qualify for future grant batches.

Lightweight QA alternative: If you just need a quick protocol-compliance check without full optimization, use the Deep Validation System Prompt instead.

Example Prompt for Cursor/Claude

I want to build an MCP server for the Context Marketplace using the CoinGecko API.

1. Use context7 to fetch the CoinGecko API documentation
2. Follow the mcp-builder-template.md workflow:
   - PHASE 1: Discover all endpoints
   - PHASE 2: Generate the product contract: target user, 5 must-win prompts, evidence fields, and ideal output surface (STOP for my review)
   - PHASE 3: Design and implement tools after I approve

Focus on a premium feature users would actually pay for, not a generic
API wrapper. The end result should either power Query answers with evidence
or provide Execute primitives with a clean normalized schema.

The builder template includes checkpoints where the AI will stop and ask for your approval before proceeding. This ensures you get tools that match your vision.

Earnings Model: You earn 90% of usage fees. Set a listing response price (e.g., $0.01/response) and get paid in USDC when agents use your tool. Want SDK developers to call your methods directly with per-call pricing too? See Enable Execute Pricing after you’re live.

Step 1: Build a Standard MCP Server

Use the official @modelcontextprotocol/sdk to build your server, plus @ctxprotocol/sdk to secure your endpoint.

Install Dependencies

pnpm add @modelcontextprotocol/sdk express
pnpm add @ctxprotocol/sdk
pnpm add -D @types/express

Implement Structured Output

Required for Context: You must implement the MCP structured output standard:

outputSchema in your tool definitions (JSON Schema describing your response structure)
structuredContent in your responses (the machine-readable data matching your schema)

outputSchema root must be `type: "object"`

The MCP specification requires the root of every outputSchema to be an object type. You cannot use anyOf, oneOf, a bare array, or a primitive at the top level — the MCP SDK will reject your tools/list response and Context will refuse to register the tool. Express variability inside properties, not at the root:

Need	Don’t	Do
Nullable value	`outputSchema: { anyOf: [ { type: "object", ... }, { type: "null" } ] }`	`outputSchema: { type: "object", properties: { price: { type: ["string", "null"] } } }`
Optional field	Union the whole schema	Omit the field from `required`
”No data” / upstream error	Discriminated union in the schema	Return `{ content: [...], isError: true }` in the response
One of several shapes	`oneOf` at the root	One `type: "object"` root with all possible fields, each nullable as needed

// ❌ Rejected — anyOf at the root
outputSchema: {
  anyOf: [
    { type: "object", properties: { venue: { type: "string" } } },
    { type: "null" },
  ],
}

// ✅ Correct — object at the root, nullability expressed per-field
outputSchema: {
  type: "object",
  properties: {
    venue: { type: "string" },
    current_price: { type: ["string", "null"] },
    funding_rate: { type: ["string", "null"] },
  },
}

Every reference server in @ctxprotocol/sdk/examples/server follows this pattern. If you need to signal a no-data / upstream-error case at runtime, use the MCP isError: true response flag — don’t encode it in the schema.

const TOOLS = [{
  name: "get_gas_price",
  description: "Get current gas prices for any EVM chain",
  inputSchema: {
    type: "object",
    properties: {
      chainId: {
        type: "number",
        description: "EVM chain ID",
        default: 1,
        examples: [1, 10, 8453],
      },
    },
  },
  outputSchema: {
    type: "object",
    properties: {
      gasPrice: { type: "number" },
      unit: { type: "string" },
    },
    required: ["gasPrice", "unit"],
  },
}];

return {
  content: [{ type: "text", text: JSON.stringify(data) }],
  structuredContent: data,
};

Use standard JSON Schema keys in inputSchema properties to guide argument generation:

default: fallback value the AI uses when the user doesn’t specify one (e.g., "default": "BTC")
examples: sample values the AI references to understand valid inputs (e.g., "examples": ["BTC", "ETH", "SOL"])

The platform reads these fields when generating arguments for your methods and when selecting the right method for a query. Without strong schema hints, the runtime has to guess valid values from the description alone, leading to more retries and lower first-pass success rates.Do not add custom _meta.inputExamples; _meta should only carry tool metadata such as pricing, context requirements, and rate-limit hints.

Optimizing Outputs for AI Context Windows

Context’s query pipeline uses model-aware data budgets when preparing tool output for synthesis. To maximize answer quality:Best practices for structuredContent:

Return structured objects (not one giant serialized string blob)
Keep textual analysis/news in dedicated string fields (these are prioritized first)
Keep large time-series arrays in separate keys from analysis text
Include a compact summary object alongside deep raw data when possible
Aim for payloads under ~500K chars for full visibility across all supported models

// ✅ Good: separated and prioritizable
return {
  summary: { direction: "outflow", confidence: 0.82 },
  news: "ETF outflows accelerated this week due to ...",
  chart: { timestamps: [...], values: [...] },
};

// ❌ Bad: giant opaque blob (hard to prioritize/truncate safely)
return JSON.stringify(allData);

Write Detailed Output Schemas (Performance Critical)

Your outputSchema is the single most impactful thing you can do to reduce latency and cost for users.Context’s managed runtime reads your outputSchema to decide how to call your tool with schema-guided arguments, how to interpret the structuredContent you return, and when to retry. If your schema is vague, the iterative loop has to guess property names, and it will guess wrong. Each bad guess triggers an extra tool-loop step that:

Adds ~30-60 seconds of latency
Costs ~$0.02 extra in model inference
Consumes retry budget within the turn

The #1 cause of these retries? Property name mismatches between what the iterative loop expects (from your outputSchema) and what your tool actually returns in structuredContent.The runtime retries likely tool-call / data-shape issues. Infrastructure failures (rate limits, auth failures, upstream timeouts) are treated as non-healable for that turn.If your tool explicitly reports plan/tier capability limits (for example, “long/short ratio unavailable on current tier”), the platform treats that as a constraint signal and returns best-effort output plus limitations instead of looping.Expose capability flags in structuredContent (for example, supportsLongShortThresholdCheck: false) and include a human-readable limitations field to help the verifier distinguish true parsing bugs from plan constraints.Document the exact property names your API returns. If your API returns snake_case, declare snake_case in your outputSchema so the runtime reads the right paths. The iterative loop calls your tool with schema-guided arguments and reads structuredContent directly — there is no generated JavaScript that “defaults to camelCase” — but the schema still has to name the fields you actually return, or the loop will look for fields that are not there.

// ❌ Bad: Vague schema; loop must guess property names
outputSchema: {
  type: "object",
  properties: {
    data: { type: "array" }
  }
}

// ✅ Good: Detailed schema with exact property names and descriptions
outputSchema: {
  type: "object",
  properties: {
    data: {
      type: "array",
      description: "Array of exchange balance objects, one per exchange",
      items: {
        type: "object",
        properties: {
          exchange_name: { type: "string", description: "Exchange name (e.g. 'Binance')" },
          total_balance: { type: "number", description: "Total balance in the queried coin" },
          balance_change_1d: { type: "number", description: "Balance change in last 24 hours" },
          balance_change_percent_1d: { type: "number", description: "Percent change in last 24 hours" },
        }
      }
    },
    fetchedAt: { type: "string", description: "ISO 8601 timestamp" }
  }
}

Output schema checklist:

Document every property name in the response, especially if they’re snake_case
Include items.properties for arrays, don’t just say { type: "array" }
Add descriptions that explain what values mean (units, ranges, interpretation)
If the response is an object (not an array), say so, { type: "object" } not { type: "array" }
Document wrapper properties your handler adds (e.g., fetchedAt, count, symbol)

For third-party APIs with strict quotas, publish pacing hints via _meta.rateLimit. The runtime uses these hints to pace calls to your API. See Tool Metadata.

Secure Your Endpoint

Add Context’s middleware to verify that requests are legitimate:

import express from "express";
import { createContextMiddleware } from "@ctxprotocol/sdk";

const app = express();
app.use(express.json());

app.use("/mcp", createContextMiddleware());

Returning Images from Tools

If your tool generates charts, heatmaps, screenshots, or other visual content, you are responsible for hosting the images and returning URLs that the AI can reference.Do not return base64-encoded images in your tool responses. Large base64 strings bloat the response, slow down processing, and may hit token limits. Instead, host your images and return URLs.Recommended: Return Image URLs

return {
  content: [
    { type: "text", text: "Analysis complete. Here's the chart:" }
  ],
  structuredContent: {
    summary: "Market analysis shows bullish signals...",
    chart_url: "https://your-cdn.com/charts/eth-analysis-12345.png",
    chart_alt: "ETH price chart with support levels marked"
  }
};

Image Hosting Options

Option	Best For
Your existing CDN	If you already have infrastructure
Cloud storage (S3, GCS, Azure Blob)	Pre-signed URLs for generated content
Vercel Blob / Cloudflare R2	Simple, cheap storage for generated images
Imgix / Cloudinary	Image transformation and optimization

Output Schema for Image Tools

{
  "type": "object",
  "properties": {
    "summary": {
      "type": "string",
      "description": "Text summary of the analysis"
    },
    "chart_url": {
      "type": "string",
      "format": "uri",
      "description": "URL to the hosted chart image"
    },
    "chart_alt": {
      "type": "string",
      "description": "Accessible description of the image"
    }
  },
  "required": ["summary", "chart_url"]
}

The AI will include your image URL in its response, and users can click to view. For the best experience, use publicly accessible URLs (no auth required) with reasonable cache headers.

Free vs Paid Security Requirements:

Tool Type	Security Middleware	Rationale
Free Tools ($0.00)	Optional	Great for distribution and adoption, anyone can call your endpoint
Paid Tools ($0.01+)	Mandatory	We cannot route payments to insecure endpoints

If you’re building a free tool, you can skip the middleware entirely. However, if you ever want to charge for your tool, you’ll need to add it.

MCP Security Model

Understanding what’s protected: Not all MCP methods require authentication. Discovery methods are open so agents can find your tools, but execution requires payment verification.

MCP Method	Auth Required	Why
`initialize`	❌ No	Session setup
`tools/list`	❌ No	Discovery - agents need to see your schemas
`resources/list`	❌ No	Discovery
`prompts/list`	❌ No	Discovery
`tools/call`	✅ Yes	Execution - costs money, runs your code

This means:

Anyone can call /mcp with initialize or tools/list to discover your tools
Only requests with a valid Context Protocol JWT can call tools/call
The middleware handles this automatically - you don’t need to implement it yourself

Step 2: Test Your Tool Locally

Before deploying, ensure your server works as expected. You can use the official MCP Inspector or curl to test your tool locally.

Using Curl

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

Step 3: Deploy Your Server

Your server needs to be publicly accessible. We support both transport methods:

Transport	URL Format	Recommendation
HTTP Streaming	`https://your-server.com/mcp`	✅ Recommended
SSE (Server-Sent Events)	`https://your-server.com/sse`	Supported

Deploy to any platform: Vercel, Railway, Render, AWS, or your own infrastructure. The only requirement is a publicly accessible HTTPS endpoint.

Step 4: Register in the App

Go to /contribute

Navigate to the contribute page in the running Context app

Select MCP Tool

Choose “MCP Tool” (the default option)

Paste Your Endpoint URL

Enter your publicly accessible endpoint URL

Auto-Discovery

We’ll auto-discover your skills via listTools()

Step 5: Set a Price

Set a listing response price. This is what users pay per response when your tool is used in the Context app or via client.query.run().

Two pricing surfaces: Your listing response price (~$0.10) covers Query mode, where Context is the librarian. If you also want SDK developers calling your methods directly, enable Execute pricing at ~~1/100 of your response price (~~$0.001/call). See Enable Execute Pricing below.

Price	What happens
$0.00	Free, great for adoption and getting discovered
$0.01+	Paid, you earn 90% of each response fee

Response fees are paid once per chat turn. The runtime may call your methods up to 100 times within that turn as a safety-capped orchestration limit.

Security requirement depends on price:

Free tools: Security middleware is optional; your endpoint works without JWT verification
Paid tools: Security middleware is mandatory. See Secure Your Endpoint

Compatibility: SDK/API payloads still expose legacy field names like price / pricePerQuery for now. Their billing meaning in Query mode is listing-level price per response turn. A future major release can introduce response-named aliases (for example, pricePerResponse) before deprecating legacy names.

Step 6: Stake USDC

All tools require a minimum USDC stake, enforced on-chain.

Tool Type	Minimum Stake
Free Tools	$10 USDC
Paid Tools	$10 USDC or 100× response price (whichever is higher)

Stakes are fully refundable with a 7-day withdrawal delay. This creates accountability and enables slashing for fraud.

Step 7: You’re Live!

Your MCP Tool is now available on the marketplace. Users can discover and use your tool through the Context app or client.query.run() in the SDK. Want SDK developers to also call your methods directly with per-call pricing? See Enable Execute Pricing below.

Validate Your Tool

Now that your tool is live, validate it works correctly through the marketplace, not just on your local server.

Recommended: Full Optimization Skill

The MCP Tool Optimization Skill is the recommended validation path. It goes beyond protocol compliance to prove your tool delivers genuine alpha:

Researches your vertical and identifies unique value angles
Generates and validates must-win prompts that beat free LLMs
Checks data quality from a buyer’s perspective (including external accuracy)
Audits latency metadata and fixes misclassifications
Iterates on fixes until pass rate exceeds 85%
Generates and pushes an optimized marketplace description automatically

Requires a funded wallet. The skill makes real query calls through the platform. If your balance is zero, validation will fail. Deposit funds before running.Load it into any AI coding agent with your API key and Tool ID.

Manual: Test in the Chat App

Enable Developer Mode in Settings → Developer Settings. In the right sidebar, turn off Auto mode and select your tool. Send one of your must-win prompts and check the Developer Logs preview card at the bottom of the response for errors. See the Debugging Guide for details.

Manual: Test via the SDK

Use the TypeScript SDK or Python SDK to test both surfaces:

Query mode: client.query.run({ query: "...", tools: ["your-tool-id"], responseShape: "answer_with_evidence", includeDeveloperTrace: true }), validates your tool can support the same premium answer contract the first-party chat uses
Agent-facing Query mode: rerun the same must-win prompt with responseShape: "evidence_only" and confirm the evidence package is still useful without prose synthesis
Execute mode (if enabled): client.tools.execute({ toolId: "...", toolName: "...", args: {...} }), validates per-method call responses match your declared schemas

Lightweight QA alternative: For a quick protocol-compliance check without full optimization, use the Deep Validation System Prompt. It validates your server against the Context Protocol docs, tests both surfaces, and provides actionable fixes. Use this when you just want to confirm things work, use the optimization skill when you want to prove your tool is worth paying for.

If you are validating a local or preview runtime on your own machine, prefer omitting agentModelId (uses the managed default) unless you are intentionally comparing models. Kimi K2.6 is the platform default used by the chat app.

Updating Your Tool

When you add new endpoints, modify schemas, or change your tool’s functionality:

Deploy Changes

Push your updated code to your server/hosting

Refresh Skills on Context

Go to ctxprotocol.com/developer/tools → Developer Tools (My Tools)
Find your tool and click “Refresh Skills”
Context re-calls listTools() to discover changes

Update Description (if needed)

If you’ve added significant new tools, update your description. Two options:

Recommended: Re-run the Optimization Skill, it regenerates and pushes the description plus validated suggestedPrompts automatically via the SDK
Programmatic: Use client.developer.updateTool(toolId, { description: "...", suggestedPrompts: [{ text: "What are the top markets right now?", source: "sdk" }] }) directly from the TypeScript SDK or Python SDK
Manual: Edit your tool in the Developer Tools page

Try asking: is now first-class marketplace metadata. Context parses that section into clickable prompt chips in the chat sidebar. If the section is missing or too weak, Context can generate example prompts from your discovered MCP methods so legacy and newly submitted tools render consistently.

Don’t forget to Refresh Skills! Deploying new code doesn’t automatically update the marketplace listing. You must click “Refresh Skills” for Context to re-discover your tools.

Complete Server Example

Here’s a full working example of an MCP server ready for Context:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
import express from "express";
import { createContextMiddleware } from "@ctxprotocol/sdk";

const app = express();
app.use(express.json());

app.use("/mcp", createContextMiddleware());

const TOOLS = [{
  name: "get_gas_price",
  description: "Get current gas prices",
  inputSchema: {
    type: "object",
    properties: {
      chainId: {
        type: "number",
        description: "EVM chain ID",
        default: 1,
        examples: [1, 10, 8453],
      },
    },
  },
  outputSchema: {
    type: "object",
    properties: {
      gasPrice: { type: "number" },
      unit: { type: "string" },
    },
    required: ["gasPrice", "unit"],
  },
}];

const server = new Server(
  { name: "my-gas-tool", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: TOOLS,
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const data = await fetchGasData(request.params.arguments.chainId);
  
  return {
    content: [{ type: "text", text: JSON.stringify(data) }],
    structuredContent: data,
  };
});

app.listen(3000, () => {
  console.log("MCP server running on port 3000");
});

Enable Execute Pricing

By default, your tool is available in Query mode: users ask questions and Context handles orchestration for a flat per-response fee. If you also want SDK developers to call your methods directly with per-call pricing (Execute mode):

Set a default execute price

In the marketplace contribute form, enter a default execute price (e.g., $0.001). This fans out to every method’s _meta.pricing.executeUsd automatically.

Or declare pricing per method in code

For fine-grained control, add _meta to each method in your MCP server:

const TOOLS = [{
  name: "get_gas_price",
  description: "Get current gas prices",
  _meta: {
    surface: "both",
    queryEligible: true,
    latencyClass: "instant",
    pricing: {
      executeUsd: "0.001",
    },
    rateLimit: {
      maxRequestsPerMinute: 60,
      cooldownMs: 1000,
      maxConcurrency: 5,
    },
  },
  inputSchema: { /* ... */ },
  outputSchema: { /* ... */ },
}];

Visibility is bidirectional:

No execute price → invisible in Execute. Methods without _meta.pricing.executeUsd will not appear in SDK Execute discovery (client.tools.execute()). Set execute pricing to unlock per-call revenue.
Execute-only → invisible in Query. If you set surface: "execute" and queryEligible: false, your methods will not appear in the Context app or client.query.run(). They become SDK-only tools.

See Choosing a Mode for the full visibility matrix.

Execute pricing is typically ~1/100 of your listing response price (e.g., $0.10 response → $0.001 per execute call) because a single Query response can invoke up to 100 method calls internally.

See Tool Metadata for the full metadata reference. For production examples, see the Polymarket contributor server (large-surface Query-mode tool with 20+ methods) and the Normalized Data Provider (Execute-mode data broker with background ingestion).

Advanced Topics

Schema Accuracy & Dispute Resolution

Your outputSchema isn’t just documentation, it’s a contract.Context uses automated schema validation as part of our crypto-native dispute resolution system:

Users can dispute tool outputs by providing their transaction_hash (proof of payment)
Robot judge auto-adjudicates by validating your actual output against your declared outputSchema
If schema mismatches, the dispute is resolved against you automatically
Repeated violations (5+ flags) lead to tool deactivation

Example: Schema Compliance

// ❌ BAD: Schema says number, but you return string
outputSchema: { temperature: { type: "number" } }
structuredContent: { temperature: "72" }  // GUILTY - schema mismatch!

// ✅ GOOD: Output matches schema exactly
outputSchema: { temperature: { type: "number" } }
structuredContent: { temperature: 72 }  // Valid

Unlike Web2 “star ratings” that can be gamed by bots, Context disputes require economic proof (you paid for the query). This protects honest developers from spam while ensuring bad actors face consequences.

Execution Limits & Product Design

Critical: MCP tool execution on the Context platform has a 60-second timeout per call. This is a single, uniform budget: it is identical in Query and Execute mode, and identical for every method regardless of its latencyClass. (latencyClass controls discovery eligibility — e.g. Query skips streaming methods — it does not grant a method more execution time.) It shapes the marketplace toward high-quality data products, but what “high-quality” means depends on which mode you’re designing for.Where the Timeout Comes FromThe timeout is enforced by the platform infrastructure (and in standard MCP setups like Claude Desktop, by the LLM client itself). When your tool is called, the system waits for a response; if it doesn’t arrive within 60 seconds, execution fails. The platform passes this same value to the underlying MCP request timer, so there is no second, hidden timeout that can cut a call short earlier.When a timeout is hit, the runtime propagates cancellation to in-flight MCP calls to avoid post-timeout “zombie” traffic. Tool authors should still return explicit failure/degraded states quickly so agents can recover gracefully.This isn’t an MCP protocol limitation, SSE connections can stay open indefinitely. The timeout exists at the application layer and serves as a quality forcing function for both modes.Designing for Query ModeIn Query mode, Context is the librarian. Your tool output feeds into a synthesized response that costs the user ~$0.10. The user expects curated intelligence, not raw data dumps.The timeout forces you to pre-compute insights rather than running heavy queries at request time:

Raw Access (❌ Bad Query Tool)	Curated Intelligence (✅ Good Query Tool)
“Run any SQL on Dune"	"Smart Money Wallet Tracker"
"Query 4 years of NFT data"	"NFT Alpha Signals"
"Scan all whale wallets"	"Whale Alert Feed”
Timeout after 60s ❌	Instant response ✅

The best data businesses don’t sell raw database access. They sell curated, pre-computed insights. This is exactly how Bloomberg, Nansen, Arkham, and Messari work, and it’s the right model for Query mode.

┌─────────────────────────────────────────────────────────────────────┐
│              QUERY MODE: DATA BROKER'S JOB (offline)                │
│                                                                     │
│  1. Run heavy queries on your data source (30 min timeout - OK)    │
│  2. Pre-compute valuable insights ("wallets that sold tops")       │
│  3. Store results in your own database                             │
│  4. Update daily/hourly via cron jobs                              │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│                    MCP TOOL (instant)                               │
│                                                                     │
│  User: "What are the smart money wallets holding?"                 │
│  Tool: SELECT * FROM my_precomputed_smart_money LIMIT 10           │
│  Response: < 1 second ✅                                            │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Designing for Execute ModeIn Execute mode, the developer’s agent is the librarian. The agent makes many sequential calls within a session, iterating over structured data to build its own analysis. The user pays ~$0.001 per call.Here, normalized data endpoints ARE the product. The value isn’t in pre-digested insights, it’s in clean, typed, consistent data that an agent can iterate over without parsing 15 different exchange APIs.The timeout still applies per-call (a single normalized price lookup shouldn’t take 60 seconds), but the design principles are different:

Inconsistent Data (❌ Bad Execute Tool)	Normalized Data (✅ Good Execute Tool)
Different schema per exchange	Unified `{ exchange, price, volume }` across all exchanges
Untyped JSON blobs	Strict `outputSchema` with typed fields
One method returns everything	Focused methods: `get_prices`, `get_orderbook`, `get_funding_rates`
No pagination or filtering	Parametric access: symbol, exchange, time range
Inconsistent error formats	Structured error responses with codes

┌─────────────────────────────────────────────────────────────────────┐
│            EXECUTE MODE: DATA NORMALIZER'S JOB (ongoing)            │
│                                                                     │
│  1. Connect to upstream sources (exchange APIs, data providers)     │
│  2. Normalize schemas into consistent typed formats                │
│  3. Expose focused, single-purpose methods                         │
│  4. Return clean, paginated, parametric data per call              │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│                    AGENT PIPELINE (iterative)                       │
│                                                                     │
│  Agent: get_prices("BTC/USDT", exchanges=["binance","coinbase"])   │
│  Agent: get_orderbook("BTC/USDT", exchange="binance", depth=20)    │
│  Agent: get_funding_rates("BTC/USDT")                              │
│  Agent: → runs own analysis across all results                     │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Product Tiers by ModeQuery mode tiers:

Real-time curated (< 60s): direct API calls that return analyzed results quickly (portfolio risk score, gas price recommendation)
Pre-computed intelligence (instant): heavy analysis run offline via cron, insights served instantly (smart money wallets, whale alerts, trending signals)

Execute mode tiers:

Normalized data endpoints: clean, typed, paginated data across multiple sources with a consistent schema (cross-exchange prices, historical time-series, order book snapshots). The value is in the normalization and reliability.
Specialized computation methods: one method does one calculation well (risk score for a wallet, correlation between two assets, signal detection). The developer chains these together.

What if my analysis takes longer than 60 seconds?For Query mode: pre-compute it. Run heavy analysis offline, store results in your database, serve instantly through MCP.For Execute mode: break it into smaller methods. Instead of one method that analyzes all wallets, expose get_wallet_activity per wallet, let the agent iterate.

// ❌ BAD (either mode): Long-running analysis at request time
{ name: "analyze_all_wallets", returns: "timeout after 60s" }

// ✅ GOOD (Query): Pre-computed results served instantly
{ name: "get_smart_money_wallets", returns: "instant curated insight from your DB" }

// ✅ GOOD (Execute): Focused method the agent calls per-wallet
{ name: "get_wallet_activity", inputs: "{ address, timeRange }", returns: "normalized activity data" }

	Query Mode	Execute Mode
Value proposition	Curated insights (quality)	Normalized data (consistency)
Competes on	Analysis depth	Schema reliability, coverage
Moat	Expertise in pre-computation	Normalization across sources
User expectation	One response = complete answer	Many calls = building blocks

Need your tool to execute transactions or get user signatures? Use the Handshake Architecture:

import { createSignatureRequest, wrapHandshakeResponse } from "@ctxprotocol/sdk";

if (needsUserSignature) {
  return wrapHandshakeResponse(
    createSignatureRequest({
      domain: { name: "MyProtocol", version: "1", chainId: 1 },
      types: { Order: [{ name: "amount", type: "uint256" }] },
      primaryType: "Order",
      message: { amount: 1000 },
      meta: { description: "Place order", protocol: "MyProtocol" },
    })
  );
}

The Context app will show an approval card, the user signs, and the signature is returned to your tool.

Handshake Architecture Guide

Full guide: signatures, transactions, OAuth flows

Example Servers

Check out these complete working examples:

TypeScript (Express + MCP SDK)

Blocknative

Query mode: Gas price API (3 tools), great starting point for your first tool

Hyperliquid

Query mode: DeFi analytics (16+ tools, includes handshake example)

Polymarket

Query mode: prediction market intelligence

Normalized Data Provider

Execute mode: reference with background ingestion, _meta pricing, and multi-exchange normalization

Python (FastMCP + ctxprotocol)

Hummingbot Market Intel

Query mode: multi-exchange market data (6 tools): prices, order books, funding rates, trade impact analysis

The Python example uses FastMCP which auto-generates outputSchema from Pydantic models and includes structuredContent in responses automatically.

​Overview

​Start With A Product Contract

​Optional Search Helpers For Search-Hard Venues

​AI-Assisted Builder (TL;DR)

​Three-Step Workflow

​Example Prompt for Cursor/Claude

​Step 1: Build a Standard MCP Server

​Install Dependencies

​Implement Structured Output

​outputSchema root must be type: "object"

​Secure Your Endpoint

​MCP Security Model

​Step 2: Test Your Tool Locally

​Using Curl

​Step 3: Deploy Your Server

​Step 4: Register in the App

​Step 5: Set a Price

​Step 6: Stake USDC

​Step 7: You’re Live!

​Validate Your Tool

​Updating Your Tool

​Complete Server Example

​Enable Execute Pricing

​Advanced Topics

​Advanced: User Actions (Handshakes)

Handshake Architecture Guide

​Example Servers

​TypeScript (Express + MCP SDK)

Blocknative

Hyperliquid

Polymarket

Normalized Data Provider

​Python (FastMCP + ctxprotocol)

Hummingbot Market Intel

Overview

Start With A Product Contract

Optional Search Helpers For Search-Hard Venues

AI-Assisted Builder (TL;DR)

Three-Step Workflow

Example Prompt for Cursor/Claude

Step 1: Build a Standard MCP Server

Install Dependencies

Implement Structured Output

outputSchema root must be `type: "object"`

Secure Your Endpoint

MCP Security Model

Step 2: Test Your Tool Locally

Using Curl

Step 3: Deploy Your Server

Step 4: Register in the App

Step 5: Set a Price

Step 6: Stake USDC

Step 7: You’re Live!

Validate Your Tool

Updating Your Tool

Complete Server Example

Enable Execute Pricing

Advanced Topics

Advanced: User Actions (Handshakes)

Example Servers

TypeScript (Express + MCP SDK)

Python (FastMCP + ctxprotocol)