MCP concepts
How an MCP client, the local Doclight MCP server and the Doclight API relate, how tools are discovered, and how your credential decides which tools exist.
The Model Context Protocol (MCP) lets an AI client call tools exposed by a separate program. Doclight ships such a program so that a client like Claude Code can read your visibility data, and optionally create projects and prompts or start a measurement run, through your own scoped credential.
The three parts
MCP client ──stdio──▶ doclight-mcp (local process) ──HTTPS──▶ Doclight API (/api/v1)
(Claude Code, ...) runs on your machine api.doclight.app- MCP client: the application you talk to. It starts the server as a child process and sends it requests over standard input and output.
- Doclight MCP server (
doclight-mcp): a small Python program on your machine. It translates tool calls into requests to the versioned/api/v1API, using the key inDOCLIGHT_API_KEY. It never prints to stdout other than MCP protocol messages. - Doclight API: the hosted service that holds your data and enforces access on every request.
Local only: no hosted MCP URL, no OAuth
There is no hosted Doclight MCP endpoint to paste into a client, and no OAuth sign-in flow. The server is a local stdio program authenticated with an API credential. Clients that only accept a remote URL cannot use it today.
How a client discovers and calls tools
- The client starts
doclight-mcpand sendsinitialize. - The client asks for the tool list (
tools/list). Each tool comes with a JSON input schema, an output schema and annotations such asreadOnlyHint. - When you ask something the tools can answer, the model chooses a tool and the client sends
tools/callwith arguments. - The server calls
/api/v1, and returns structured results, or a short error message that is safe to show.
Read tools declare readOnlyHint=true. Write tools are annotated readOnlyHint=false and destructiveHint=false, and
their descriptions start with MUTATION so a client can ask you to confirm before running them.
Your credential decides which tools exist
At startup the server asks the API what the configured key may do (GET /api/v1/credential):
| Key | Tools offered |
|---|---|
read scope | list_brands, list_questions, get_visibility_summary, get_run_status |
write scope | The four read tools, plus add_prompt and trigger_run |
write scope and authorised for a workspace | All of the above, plus create_project |
| Unknown (no key, network failure, older API) | Read tools only |
Offering a tool is a convenience, not a security boundary. The API re-checks scope, revocation, paid access, rate limit and brand membership on every call, so tool arguments can never widen what the key may do. Because tools are decided at startup, restart the client (or reload the server) after changing a key's scope.
What the tools are for
The tools are scoped to the same data as the /api/v1 surface: brands, tracked questions, runs and the report
summary. Numbers are API-model measurements; see Metrics and methodology.
There is no scheduling, bulk setup or deletion through MCP.
Getting started
Prerequisites, creating a scoped API credential, and making your first successful read through the Doclight MCP server.
Installation and connection
Install the Doclight MCP server and register it with Claude Code, Claude Desktop, Cursor or VS Code, with configuration locations for each client.