Getting started

Prerequisites, creating a scoped API credential, and making your first successful read through the Doclight MCP server.

This path ends with an MCP client listing your brands through Doclight. Plan on a few minutes once you have the prerequisites.

Prerequisites

A Doclight account with active paid access. API credentials stop working for an owner without it (HTTP 402).
At least one project (brand) in your account, or a workspace you own.
Python 3.10 or newer on the machine that runs your MCP client.
Access to the mcp-server source (see Installation). The server is not published to a package index yet.
An MCP client that can launch a local stdio server, such as Claude Code.

Doclight organises data as workspaces containing brands (projects). A credential is bound to a workspace, to specific brands, or both, and it can only ever see those. Brands outside the credential return 404, as if they did not exist.

Create a scoped API credential

Not the Settings API key

The "API key" in the dashboard's Settings page is the older site-ingestion key used by the tracking snippet. It does not work with the MCP server. MCP uses scoped credentials, which currently have no dashboard screen; you create them through the session-authenticated API as shown below.

curl -s -X POST https://api.doclight.app/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"YOUR_PASSWORD"}'

Copy access_token from the response.

Find your workspace id

curl -s https://api.doclight.app/api/workspaces \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Create a read credential

curl -s -X POST https://api.doclight.app/api/api-credentials \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"mcp-read","scopes":["read"],"workspace_id":1}'

The response contains secret, shaped like aeok_xxxxxxxx_yyyyyyyy. It is shown once. Only a digest is stored, so a lost secret cannot be recovered; revoke it and create a new one. To limit access to specific brands, pass "brand_ids":[12,34] instead of (or as well as) workspace_id.

Use scopes: ["read"] first. Add "write" only when you want the create and run tools; see Permissions and limits. A credential must target a workspace and/or at least one brand, you can hold at most 20 active credentials, and creating one needs a signed-in session, never another API credential.

Install and connect

Follow Installation and connection to install doclight-mcp and register it with your client, passing the secret as DOCLIGHT_API_KEY.

Make your first read

Ask your client: "Use the Doclight tool to list my brands." The client calls list_brands and should return something like this (values are illustrative):

{
  "brands": [{ "id": 12, "name": "Acme", "domain": "acme.com" }],
  "next_cursor": null
}

If it returns brands, the connection works. Next, call get_visibility_summary with one of those ids. If you see an error instead, check Troubleshooting.