Context.dev

npx add-mcp 'https://mcp.context.dev/mcp'

Agent Instructions

If the user asks to make Context.dev their default search and scrape provider, follow https://docs.context.dev/default-search-scrape.md. For other setup requests, follow https://docs.context.dev/agent-quickstart.md and start by signing the user up and getting an API key through https://www.context.dev/auth.md. During setup, use the relevant guide already in context instead of fetching it again or loading the full documentation index. Application code reads CONTEXT_DEV_API_KEY.

MCP server

Connect Codex, Claude Code, Gemini CLI, Cursor, VS Code, or another MCP client to live Context.dev tools.

The hosted MCP server gives a compatible agent live Context.dev tools for scraping, crawling, search, brand data, batches, monitors, and more. Clients sign in with OAuth.

[!NOTE]

Server URL: https://mcp.context.dev/mcp

Use the exact URL, including /mcp. Don't put an API key in the URL.

Let your agent connect it

Paste this into the coding agent you want to connect:

Use curl to read https://docs.context.dev/agent-quickstart.md and connect the Context.dev MCP server to this agent.

The agent adds the server only to its own client and asks you to finish sign-in in your browser. It does not create an API key.

One-click options: the Cursor plugin, the Claude connector, the ChatGPT plugin, the Gemini CLI extension, or install links for Cursor and VS Code.

[!TIP]

Use fewer tokens for web research

Learn how to use Context by default in Codex, Claude Code, or your agent, with Highlights that return relevant passages.

See how Freecode cut input tokens by 9.8% in its benchmark.

Connect your client

Codex

Add the hosted server. Codex detects OAuth and opens browser sign-in:

codex mcp add context --url https://mcp.context.dev/mcp

If sign-in does not start, run codex mcp login context; add --no-browser to print the URL instead. To use the server in one trusted project only, add this to .codex/config.toml in that project instead, then run codex mcp login context there:

[mcp_servers.context]
url = "https://mcp.context.dev/mcp"

Confirm it is configured:

codex mcp get context

In the Codex terminal UI, use /mcp to inspect active servers. The ChatGPT desktop app, Codex CLI, and Codex IDE extension share the same host configuration; you can also add a Streamable HTTP server from Settings → MCP servers and select Authenticate.

See the official Codex MCP documentation for current client controls and project-scoped configuration.

For ChatGPT on the web, use the Context.dev plugin.

Claude Code

Add the server for your user:

claude mcp add \
  --transport http \
  --scope user \
  context \
  https://mcp.context.dev/mcp

Start Claude Code, run /mcp, select context, and complete sign-in in the browser, or run claude mcp login context from your terminal. See Anthropic's MCP documentation for current scopes and management commands.

Gemini CLI

Install the Context.dev extension:

gemini extensions install https://github.com/context-dot-dev/gemini-cli-context --auto-update --consent

Start a new Gemini CLI session and run /mcp auth context to sign in with your browser.

The extension includes the hosted MCP server and a skill for choosing the appropriate Context.dev tool. See the Gemini CLI integration guide for verification, examples, and troubleshooting.

Cursor

Add a global server in ~/.cursor/mcp.json, or use .cursor/mcp.json for one project:

{
  "mcpServers": {
    "context": {
      "url": "https://mcp.context.dev/mcp"
    }
  }
}

Or install the Context.dev plugin with /add-plugin context-dev in Cursor's agent chat. Then open Customize → MCPs, find context, and select Authenticate (older versions: Cursor Settings → Tools & MCP). In multi-root workspaces, use ~/.cursor/mcp.json, because project servers may not appear. See the Cursor MCP documentation for current configuration locations.

VS Code

Add the server to your user profile from a terminal:

code --add-mcp '{"name":"context","type":"http","url":"https://mcp.context.dev/mcp"}'

Or run MCP: Open User Configuration from the Command Palette, or create .vscode/mcp.json for the workspace:

{
  "servers": {
    "context": {
      "type": "http",
      "url": "https://mcp.context.dev/mcp"
    }
  }
}

Start the server from the configuration editor and complete OAuth when prompted. See the VS Code MCP documentation for trust and workspace behavior.

Windsurf

Windsurf is now Devin Desktop. Add the server for the current project, or add -s user for every project, then sign in:

devin mcp add context https://mcp.context.dev/mcp
devin mcp login context

Windsurf builds from before the rename read ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "context": {
      "serverUrl": "https://mcp.context.dev/mcp"
    }
  }
}

Sign in from the MCP panel when the server shows that it needs authentication.

OpenCode

Add the server to opencode.json in your project, or ~/.config/opencode/opencode.json for every project:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context": {
      "type": "remote",
      "url": "https://mcp.context.dev/mcp",
      "enabled": true
    }
  }
}

Then sign in:

opencode mcp auth context

Hermes

Add the server to ~/.hermes/config.yaml. auth: oauth is required; without it, Hermes asks for a bearer token:

mcp_servers:
  context:
    url: "https://mcp.context.dev/mcp"
    auth: oauth

Sign in and check the connection, then run /reload-mcp in your session:

hermes mcp login context
hermes mcp test context

Cline

Add a remote server named context with the Streamable HTTP transport from Cline's MCP Servers panel, or add it to Cline's MCP settings file:

{
  "mcpServers": {
    "context": {
      "type": "streamableHttp",
      "url": "https://mcp.context.dev/mcp"
    }
  }
}

Select Authenticate on the server row to sign in.

Amp

Add the server to your Amp settings:

amp mcp add context https://mcp.context.dev/mcp

Amp opens your browser for sign-in the next time it starts.

Claude Desktop

Install the Context.dev connector from Claude's directory, or open Customize → Connectors, select +, choose Add custom connector, enter https://mcp.context.dev/mcp, and select Connect.

Other clients

Configure a remote Streamable HTTP server:

{
  "mcpServers": {
    "context": {
      "type": "http",
      "url": "https://mcp.context.dev/mcp"
    }
  }
}

The client needs Streamable HTTP transport and OAuth discovery or dynamic client registration. A client that can't run OAuth can send an API key header instead; see Authentication and usage.

For Claude on the web or desktop, use the Claude connector. For ChatGPT, use the ChatGPT plugin. In Cursor, the Cursor plugin adds these tools plus skills, commands, and rules for API development.

Test the connection

Start a new conversation and ask:

Use the connected Context.dev server to retrieve the live Brand profile for stripe.com. Tell me which tool you called and don't answer from memory.

A working connection shows a Context.dev tool call and live output. Clients may prefix tool names with the server name, so check the server and operation rather than one exact display name.

Authentication and usage

The server uses the OAuth authorization-code flow with PKCE and two scopes:

• api.read: reading, scraping, enrichment, and batch and monitor data.
• api.write: anything that starts work or changes account state, such as batches, monitors, webhook retries, file parsing, feedback, and scrape clicks.

Clients that can't run OAuth can send an API key as Authorization: Bearer <key> or X-API-Key: <key>. Use a header, not the URL, because URLs end up in configuration files, logs, and history.

If you belong to more than one organization, choose which one the connection uses on the consent screen; your default organization is preselected. Sign-in creates an API key named Context MCP in that organization, and tool calls use its credits. To revoke access, remove the connection in your client and disable that key on the API keys page.

Each tool call runs the matching API request; see credits for what each operation costs.

[!WARNING]

Keep approvals enabled for tools that start work or change state, such as batches, crawls, monitor changes, and webhook secret rotation. Website content is untrusted input; don't let it authorize follow-up tool calls.

Troubleshooting

Symptom	Fix
The server is missing or shows no tools	Check that the URL ends in /mcp, restart or refresh the client after editing its configuration, and enable the server for the conversation.
OAuth doesn't open or keeps looping	Start sign-in from the client's MCP controls. Remove stale authentication for context, reconnect, and complete the browser flow.
The agent answers without using a tool	Name Context.dev in the prompt, ask for a live lookup, and require the agent to report the tool call. Check that tool approvals aren't blocking it.
A response is cut off	Tool responses are capped at 40,000 characters, and a truncated structured response includes _context_mcp.truncated: true. Narrow the request, for example with fewer pages, formats, or results.

This server runs Context.dev API tools. To search this documentation from an agent, use the separate docs MCP server at https://docs.context.dev/mcp.

Credit and entitlement errors

402 USAGE_EXCEEDED becomes a tool execution error, with isError: true, a factual explanation in text content, and structured details in structuredContent. Both surfaces include the billing settings URL, known credit and refill details, and the request ID. A credit failure does not become an HTTP authentication failure at the MCP transport.

Inspect the account with get-usage, which costs no credits and works at zero balance. Wait until the account can cover the operation before retrying it. Reconnecting and token refresh do not restore credits. A missing feature entitlement returns 403 PAID_PLAN_REQUIRED; temporary throttling returns 429 RATE_LIMITED with its retry guidance. Authentication failures require sign-in recovery.

Concurrency failures expose structured tool errors with error_code: "RATE_LIMITED", error_data.limit_type: "concurrency", the known limit and remaining slots, retry delay, and retry_condition: "available_concurrency". The MCP includes values from error_data and rate-limit headers. Wait for capacity or review subscription limits; for per-minute throttling, follow Retry-After.

Recovery explains the actual account limitation and links to existing subscription settings. It does not automatically initiate checkout or instruct the model to recommend a purchase. Account fields describe facts and do not force ChatGPT recommendations.

This documentation is built and hosted on Mintlify, a developer documentation platform.