> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://mediacontext.dev/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://mediacontext.dev/docs/_mcp/server.

# MCP client setup

The hosted MCP endpoint is `https://app.mediacontext.dev/api/v1/mcp`. It speaks Streamable HTTP, exposes 13 read-only tools, and authenticates with OAuth or a MediaContext API key. Every call runs inside your workspace and counts against its API allowance.

## Sign in with OAuth

OAuth clients discover the connection automatically. The authorization server is the workspace identity provider, and access tokens grant read-only tool access.

### ChatGPT

1. Open **Settings > Connectors**, enable Developer or Advanced mode, and add a custom connector.
2. Enter `https://app.mediacontext.dev/api/v1/mcp` as the server URL.
3. Sign in with your MediaContext account when prompted.

### Codex

Register the server, then log in:

```sh
codex mcp add mediacontext --url https://app.mediacontext.dev/api/v1/mcp
codex mcp login mediacontext
```

To use an API key instead of OAuth, point the environment variable at a read-scoped key:

```sh
codex mcp add mediacontext --url https://app.mediacontext.dev/api/v1/mcp --bearer-token-env-var MEDIACONTEXT_API_KEY
```

### Claude and other OAuth-capable clients

Add `https://app.mediacontext.dev/api/v1/mcp` as a custom connector or remote MCP server and complete the sign-in. Any client that implements OAuth discovery with the protected resource metadata at `/.well-known/oauth-protected-resource` can connect without an API key.

Accounts with several workspaces connect to their first workspace by default. Pass `?workspace=<slug>` on the endpoint URL to select another; the server lists your workspace slugs when it cannot pick one.

## Use an API key

Clients without OAuth can send a MediaContext API key in either header: `X-Api-Key` or `Authorization: Bearer`.

1. In **Settings > API access**, create a key with `read` scope and save its one-time secret.
2. Add the key as `X-Api-Key` or as a bearer token in your client's MCP server settings for `https://app.mediacontext.dev/api/v1/mcp`.

The key owner's current pro entitlement is required. An `export`-only key is insufficient; enable `read` for MCP. Keep keys in the client's secret-aware configuration, outside URLs and logs.

## Transport behavior

The HTTP transport is stateless and accepts JSON POST requests. There is no legacy SSE endpoint or GET event stream, no persistent session ID, and no HTTP workspace mutation tools. Clients must send `Content-Type: application/json` and accept both `application/json` and `text/event-stream` as required by Streamable HTTP. JSON-RPC replies use JSON; accepted notifications can return 202 without a response body. Requests from a browser origin other than `https://app.mediacontext.dev` are rejected.

Request bodies are capped at 65,536 bytes and must arrive within 10 seconds. Each upstream application request has a 30-second timeout; a tool can make more than one application request. Redirects are rejected. HTTP authentication or transport failures use HTTP error responses; application failures inside a tool are reported as MCP tool errors. Neither a successful MCP HTTP response nor an empty result establishes that a tool succeeded: inspect its error indicator.

Unauthenticated calls return `401` with a `WWW-Authenticate` header pointing at the protected resource metadata, so OAuth-capable clients can start the sign-in flow automatically.

## Run the local stdio implementation

Install repository dependencies, build the contracts package and start the snapshot API:

```sh
npm run build --workspace @openstack/contracts
npm run server --workspace @openstack/dashboard
```

Configure a stdio-capable client to launch `npm` with arguments `--prefix`, the absolute path to `packages/dashboard`, `run`, `mcp:v1`. Supply credentials through that client's secret-aware environment configuration:

| Variable            | Purpose                                                                   |
| ------------------- | ------------------------------------------------------------------------- |
| `OPENSTACK_API`     | REST base; defaults to `http://127.0.0.1:8787`.                           |
| `OPENSTACK_API_KEY` | Scoped API key for reads. Takes precedence when both credentials are set. |
| `OPENSTACK_BEARER`  | Clerk session token for workspace reads.                                  |

The v1 server identifies itself as `mediacontext`. The environment variable prefix remains `OPENSTACK_` for compatibility. Refresh an expired Clerk session through Clerk; the proxy does not sign in or renew tokens. API keys cannot add or remove Shortlist members.

## Tool reference

The same 13 read-only tools are available through v1 HTTP and `mcp:v1` stdio. Each tool uses the corresponding `/api/v1` resource and declares both input and output schemas.

| Tool                          | Task                                                                    |
| ----------------------------- | ----------------------------------------------------------------------- |
| `search_publishers`           | Find publishers using the shared search filters and pagination.         |
| `get_publisher`               | Read a publisher's identity and evidence.                               |
| `get_publisher_technologies`  | Inspect observed providers and their provenance.                        |
| `get_publisher_ad_experience` | Read desktop and mobile ad experience evidence.                         |
| `get_publisher_changes`       | Read dated technology additions and removals.                           |
| `list_technology_providers`   | Discover provider names and categories before a comparison.             |
| `compare_provider_footprints` | Compare one or two providers in a category.                             |
| `summarize_market`            | Summarize explicit domains, a workspace list, or the served population. |
| `list_datasets`               | Discover the currently served directory and its capabilities.           |
| `list_account_lists`          | Discover list IDs in the authenticated workspace.                       |
| `get_account_list`            | Read a discovered list and its membership.                              |
| `summarize_account_list`      | Read coverage and measured metrics for a list.                          |
| `list_signal_events`          | Read workspace events and their before/after evidence.                  |

Start with `search_publishers` using `{"q":"example","limit":5}`. Use a returned domain with `get_publisher` or `get_publisher_technologies`. For list research, call `list_account_lists` first and pass a returned ID as `listId` to `summarize_account_list`.

Successful responses include validated `structuredContent` and a JSON text representation for clients that read text. Collections use the same `data`, `page` and `meta` envelopes as REST. Unknown measurements remain null. Schema-invalid upstream data is a tool error, not a successful result.

Machine-readable input and output schemas are generated at `packages/contracts/generated/mcp.json`. No resources or prompts are registered. The proxy cannot grant access beyond the credential's workspace and scopes.

### Existing clients

`POST /api/mcp` and `npm --prefix packages/dashboard run mcp` retain the legacy tool names, response shapes and behavior. They are separate from the v1 interface. The legacy stdio process retains its session-only Shortlist mutations. Existing clients should migrate deliberately; changing the endpoint changes the contract.

## Usage and failures

The workspace's API allowance is 10,000 authenticated requests per UTC calendar month, shared across its keys, OAuth sessions and REST clients. HTTP MCP initialize and tools-list requests each consume one unit. Tool calls also consume units for their underlying REST requests; each v1 tool makes one REST read, consuming two units in total over HTTP. Legacy `get_publisher` can consume four units. Failed downstream attempts still count, while requests rejected by the monthly quota do not increase usage.

MCP responses retain the lowest remaining allowance observed across their underlying reads and the latest applicable reset or retry time. A nested `429` is a tool error, which can arrive inside an HTTP 200 MCP response. Inspect the tool error and `Retry-After`; do not retry it as successful empty data.

`GET /api/v1/mcp/status` reports the endpoint, transport, read-only tool names, environment configuration and current caller availability. `MC_MCP_ACCESS_ENABLED=false` pauses HTTP MCP with `503 mcp_access_disabled`. `MC_API_KEY_ACCESS_ENABLED=false` pauses all API-key requests with `503 api_access_disabled`, including HTTP MCP and key-backed stdio. Settings reports these runtime conditions; it does not change the flags.