> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thecontextcompany.com/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP
> Connect your AI coding tools to query development and production observability data using the Model Context Protocol.
Give your coding agent direct access to your production and development data. This is especially powerful when debugging - instead of switching between your editor and dashboard, your agent can pull the exact runs, errors, and user interactions it needs to understand what's going wrong and fix it in place.
MCP is powered by [insight search](/features/insight-search), so your agent can query your production data with natural language and use that context to find root causes, fix issues, and optimize your agent.
## Prerequisites
* A [Context Company](https://thecontext.company) account with at least one project sending data
* An MCP-compatible IDE or tool (Cursor, Claude Code, Windsurf, or any client that supports MCP)
## Setup
One-click install via OAuth — no API key needed. For CI, programmatic, or headless setups, see [Advanced: API key](#advanced-api-key).
Add the server to Cursor using the [Access Data page](https://www.thecontext.company/prod/mcp-and-api) in your dashboard (use the **Add to Cursor** button), or paste the config below into **Settings > MCP Servers**:
```json theme={null}
{
"mcpServers": {
"context-company": {
"url": "https://api.thecontext.company/mcp"
}
}
}
```
After installing, click **Connect** next to `context-company` in Cursor to sign in via OAuth.
Run this in your terminal:
```bash theme={null}
claude mcp add --transport http context-company https://api.thecontext.company/mcp
```
Then run `claude`, type `/mcp`, select `context-company`, and press Enter to complete the OAuth sign-in.
For any MCP client that supports Streamable HTTP transport and OAuth:
```json theme={null}
{
"mcpServers": {
"context-company": {
"url": "https://api.thecontext.company/mcp"
}
}
}
```
Sign in through your client's MCP connection UI to complete the OAuth flow.
Try this prompt:
```
Use The Context Company MCP to show me my last 5 production agent runs, including their status and cost.
```
### Advanced: API key
For CI, programmatic, or headless setups where OAuth isn't practical, you can authenticate with a read-only API key instead.
Cursor may ignore `Authorization` headers when the MCP server advertises OAuth discovery — we recommend the OAuth flow above for Cursor. API keys still work for Claude Code, CI, and other programmatic or headless MCP clients.
Go to the [Access Data page](https://www.thecontext.company/prod/mcp-and-api) in your dashboard and create a read-only API key.
Keys are prefixed with `tcc_key` and are read-only - they can only query your data, not ingest traces.
Copy your key immediately. You won't be able to see it again.
When creating a key, choose an access scope:
| Scope | Access |
| -------------- | ---------------------------------------------------------- |
| **Dev only** | Development runs and traces |
| **Prod only** | Production runs, metrics, patterns, failures, and sessions |
| **Dev + Prod** | All dev and production data |
Run this in your terminal:
```bash theme={null}
claude mcp add --transport http context-company \
https://api.thecontext.company/mcp \
--header "Authorization: Bearer "
```
For any MCP client that supports Streamable HTTP transport:
```json theme={null}
{
"mcpServers": {
"context-company": {
"url": "https://api.thecontext.company/mcp",
"headers": {
"Authorization": "Bearer "
}
}
}
}
```
Replace `` with the key you generated.
## Available tools
For most questions, `insight_search` is the right choice — it's a multi-step analytics agent with full SQL access to your telemetry and synthesizes evidence across runs, sessions, patterns, failures, and costs. The other tools fetch raw traces and lists, and are best used when you already have a specific ID or want a filtered list of runs/sessions.
### insight\_search
Ask natural-language questions about your production data including metrics, patterns, failures, sessions, costs, and more. See [insight search](/features/insight-search) for details and example queries.
Insight search queries production data only and requires a **Pro** or **Enterprise** plan.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------- |
| `query` | string | Yes | A natural-language analytics question |
### get\_agent\_runs
Fetch a filtered raw list of runs for `dev` or `prod`. A session/run matches when its run-level fields match the supplied filters.
`summary` (the default) returns compact runs with prompt/response previews and failed step/tool-call summaries. `full_trace` includes all steps and tool calls using preview text only.
| Parameter | Type | Required | Description |
| ----------------- | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source` | `"dev"` \| `"prod"` | Yes | Data source to query |
| `timeRange` | string | No | Preset lookback window: `last_5_minutes`, `last_hour`, `last_day`, `last_two_weeks`, `last_month`, `last_two_months`. Use either `timeRange` or both `from` and `to`. |
| `from` | string | No | Start time as an ISO 8601 timestamp. Use with `to` if not using `timeRange`. |
| `to` | string | No | End time as an ISO 8601 timestamp. Use with `from` if not using `timeRange`. |
| `onlyErrored` | boolean | No | When `true`, return only errored runs. |
| `metadata` | object | No | Exact custom metadata key/value filters, e.g. `{"feature": "checkout"}`. |
| `agent` | string | No | Exact agent name filter. Matches the native `agent` column populated from [`tcc.agent`](/concepts#agents). |
| `userId` | string | No | Exact external user ID filter. Matches the native external user column populated from [`tcc.userId`](/concepts#user-and-organization-identity). |
| `orgId` | string | No | Exact external organization / customer ID filter. Matches the native external org column populated from [`tcc.orgId`](/concepts#user-and-organization-identity). This is the customer's ID in your system, **not** the Context Company platform org ID. |
| `failureContains` | string | No | Substring to match against run-level `error_class`/`status_message`. |
| `returnType` | `"summary"` \| `"full_trace"` | No | `summary` (default) returns previews and failed child summaries. `full_trace` includes all steps and tool calls. |
| `session_id` | string | No | Filter to runs in a specific session. |
| `limit` | number | No | Maximum runs to return (1–25). Defaults to 10. |
### get\_agent\_sessions
Fetch a filtered list of sessions for `dev` or `prod`. A session matches when any run in that session matches the time, metadata, errored-only, and run-level failure text filters.
| Parameter | Type | Required | Description |
| ----------------- | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source` | `"dev"` \| `"prod"` | Yes | Data source to query |
| `timeRange` | string | No | Preset lookback window: `last_5_minutes`, `last_hour`, `last_day`, `last_two_weeks`, `last_month`, `last_two_months`. Use either `timeRange` or both `from` and `to`. |
| `from` | string | No | Start time as an ISO 8601 timestamp. Use with `to` if not using `timeRange`. |
| `to` | string | No | End time as an ISO 8601 timestamp. Use with `from` if not using `timeRange`. |
| `onlyErrored` | boolean | No | When `true`, return only sessions with matching errored runs. |
| `metadata` | object | No | Exact custom metadata key/value filters, e.g. `{"feature": "checkout"}`. |
| `agent` | string | No | Exact agent name filter. Matches the native `agent` column populated from [`tcc.agent`](/concepts#agents). |
| `userId` | string | No | Exact external user ID filter. Matches the native external user column populated from [`tcc.userId`](/concepts#user-and-organization-identity). |
| `orgId` | string | No | Exact external organization / customer ID filter. Matches the native external org column populated from [`tcc.orgId`](/concepts#user-and-organization-identity). This is the customer's ID in your system, **not** the Context Company platform org ID. |
| `failureContains` | string | No | Substring to match against run-level `error_class`/`status_message`. |
| `returnType` | `"summary"` \| `"full_trace"` | No | `summary` (default) returns compact matching runs with previews. `full_trace` includes all steps and tool calls. |
| `limit` | number | No | Maximum sessions to return (1–25). Defaults to 10. |
### get\_agent\_run
Fetch the full raw trace of a single run by ID, including all steps and tool calls. Use this only when you need the complete step-by-step trace of a specific run.
| Parameter | Type | Required | Description |
| --------- | ------------------- | -------- | -------------------- |
| `source` | `"dev"` \| `"prod"` | Yes | Data source to query |
| `run_id` | string | Yes | The run ID to fetch |
### get\_agent\_session
Fetch a specific production session by session ID.
| Parameter | Type | Required | Description |
| ------------- | ---------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `session_id` | string | Yes | The session ID to fetch |
| `return_type` | `"conversation"` \| `"full_trace"` | No | `conversation` (default) returns only the prompt/response conversation. `full_trace` returns runs with steps and tool calls. |
## Example prompts
**Frustration debugging**
> Find the biggest reason users have been frustrated in my runs this past week. Look at my codebase to find the root cause and fix it.
**Tool failure chains**
> Find runs where a tool call failed right after another tool succeeded. What's the most common pattern, and what in my code is causing it?
**Cost optimization**
> Find my most expensive runs from the past week. Figure out which prompts or tool loops are driving up cost and suggest code changes to reduce token usage.
**Redundant tool loops**
> Find runs where my agent called the same tool more than 3 times in a row. Is there a loop in my code causing redundant calls? Fix it.
**Task failure improvement**
> Show me runs with task failure patterns. Compare what the user asked for vs what the agent did, and suggest how to improve my system prompt.