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
- Open Settings > Connectors, enable Developer or Advanced mode, and add a custom connector.
- Enter
https://app.mediacontext.dev/api/v1/mcpas the server URL. - Sign in with your MediaContext account when prompted.
Codex
Register the server, then log in:
To use an API key instead of OAuth, point the environment variable at a read-scoped 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.
- In Settings > API access, create a key with
readscope and save its one-time secret. - Add the key as
X-Api-Keyor as a bearer token in your client’s MCP server settings forhttps://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:
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:
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.
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.