Each project is one URL. Point a client at it, with the project’s token, and the agent gains five documentation tools — no vendor API key, no plugin.
http://localhost:3444/mcp/<project-name>
The dashboard’s Connect an agent panel prints every snippet below filled in with the real URL, ready
to copy — including the Authorization header when the project requires a token. Replace demo with
your project name in the examples, and ctxm_9f3a… with the token the project page showed you.
Claude Code
A new project requires a token by default, so add the header with your project’s token:
claude mcp add --transport http demo-docs http://localhost:3444/mcp/demo \
--header "Authorization: Bearer ctxm_9f3a…"
If the project’s MCP access was switched to open, the header can be left off:
claude mcp add --transport http demo-docs http://localhost:3444/mcp/demo
Check it worked:
claude mcp list
Then just ask a question about your documentation — Claude Code decides to call search_docs on its own,
because the server describes what it holds.
Cursor
~/.cursor/mcp.json for every project, or .cursor/mcp.json inside one repository. A new project
requires a token by default:
{
"mcpServers": {
"demo-docs": {
"url": "http://localhost:3444/mcp/demo",
"headers": { "Authorization": "Bearer ctxm_9f3a…" }
}
}
}
If the project’s MCP access was switched to open, the headers block can be left off:
{
"mcpServers": {
"demo-docs": { "url": "http://localhost:3444/mcp/demo" }
}
}
Restart Cursor, then check Settings → MCP for a green indicator.
Claude Desktop
Claude Desktop speaks stdio, so it needs a bridge. A new project requires a token by default, and
mcp-remote passes it on with --header, in claude_desktop_config.json:
{
"mcpServers": {
"demo-docs": {
"command": "npx",
"args": [
"-y", "mcp-remote", "http://localhost:3444/mcp/demo",
"--header", "Authorization:${AUTH_HEADER}"
],
"env": { "AUTH_HEADER": "Bearer ctxm_9f3a…" }
}
}
}
The token sits in env and the header argument has no space in it on purpose: on Windows, Claude
Desktop hands args to npx without escaping spaces, so "Authorization: Bearer …" arrives split in
two and every request comes back 401. It also keeps the token out of the process list.
If the project’s MCP access was switched to open, the --header argument can be left off:
{
"mcpServers": {
"demo-docs": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://localhost:3444/mcp/demo"]
}
}
}
Restart Claude Desktop. The tools appear under the connectors icon.
Config file locations: macOS ~/Library/Application Support/Claude/claude_desktop_config.json,
Windows %APPDATA%\Claude\claude_desktop_config.json.
Any other MCP client
Give it the URL — and the token, for a project that requires one. Streamable HTTP is the way to connect; the legacy transport is still served on the same address for older clients, and the server picks by what the client sends:
- Streamable HTTP (current clients, use this):
POSTaninitializerequest; the session id comes back in themcp-session-idheader. - HTTP + SSE (protocol
2024-11-05, legacy):GETthe URL; the server answers with anendpointevent pointing at/mcp/demo/messages?sessionId=…. It is deprecated — it keeps working, every response carriesDeprecation: @1790899200,Sunset: Sat, 02 Oct 2027 00:00:00 GMTand aLinkheader pointing at the compatibility policy, and new clients should not be set up on it. It may be removed in the first1.xminor release after 2027-10-02 (earlier only for a vulnerability in it that cannot be fixed).
No configuration switches between them.
Projects that require a token
A project whose MCP access is token required answers every request without a valid token with
401 and a www-authenticate: Bearer realm="<project-name>", resource_metadata="<base-url>/.well-known/oauth-protected-resource/mcp/<project-name>" header (the resource_metadata pointer is where an OAuth client starts discovery), whichever transport the client
uses. Mint the token on the project page — it is shown once — and send it as an ordinary header:
Authorization: Bearer ctxm_9f3a…
- The header is checked on every
/mcp/*request. On the legacy SSE transport that means theGETthat opens the stream and thePOSTs to/mcp/demo/messages, so a client that can set a header on only one of the two cannot connect. A browserEventSourceis the usual case — leave those projects open, or put the whole instance behind an authenticating proxy. - Tokens are per project. A client connected to two token-protected projects needs one for each.
- Revoking a token cuts its client off immediately, mid-session; so does switching a project from open to token required. Reconnecting with a current token is all that is needed.
Where the switch lives and who may flip it: Projects.
Limiting a token to some sources
Since 0.6.0 a static ctxm_… token can be bound to some of the project’s sources, so a CI job or an agent that needs one
source is not handed all of them. Pick Only these sources when you mint the token, or send sources (source names) to
POST /api/projects/:id/mcp-tokens; change it later with PATCH /api/projects/:id/mcp-tokens/:tokenId/sources. It takes
effect on the token’s next request, and minting or changing it is an editor’s.
A source outside the scope does not exist for the token: nothing of it appears in search_docs, read_document,
list_topics, whats_new (added, modified and removed rows alike), resources/list or resources/read. The filter is applied
in SQL, ahead of ranking, paging and counting, and a source name outside the scope is answered as an unknown source.
- Only a static token carries a scope. An OAuth credential is the account’s membership, and a project in account required mode refuses static tokens.
- A scope whose sources were all deleted reads nothing, never the whole project; the token list marks it Scope empty.
- On an open project a scope is not a boundary: a request with no token at all reads the whole project.
- OAuth credentials, API tokens and
/api/*are unaffected. - Going back to a release before 0.6.0 widens every scoped token to its whole project, because the older code does not read the scope. Revoke scoped tokens before a downgrade.
Projects that require an account
account required is the third mode, and the one where this dashboard’s memberships reach /mcp/*.
A static ctxm_… token names nobody and is refused there; a client has to act as an account that is a
member of the project, and that is re-checked on every request — removing a membership,
disabling an account or resetting its password cuts the connection off on its next call rather than at
some expiry.
A client gets that credential through OAuth 2.1, which is what browser-based MCP connectors already
speak. You configure nothing: point the connector at http://host:3444/mcp/<project-name>, and it
discovers this server’s authorization endpoints, registers itself, and sends you to a page here to sign
in and approve it. What it gets back acts as your account, renews itself quietly, and expires if the
connector goes unused for a month. Changing your password disconnects every connector acting as you.
A connector can identify itself in one of two ways: register through /oauth/register, or send an https:// URL
with a path as its client_id — a Client ID Metadata Document (CIMD) — and skip the registration call. The
authorization server announces the second with client_id_metadata_document_supported: true. The server fetches the
document through the same egress guard Confluence uses (https only, and never a loopback, link-local, private or
unspecified address, checked after DNS and on every redirect), reads at most 5 KiB, waits at most 5 seconds, and
keeps it as long as its Cache-Control or Expires header allows — 5 minutes without one, a day at most. The
document’s client_id must equal the URL, client_name and redirect_uris are required, a secret is refused, and
the redirect_uri the client asks for must be listed in it exactly. The approval page names the host that published
the document and where the answer goes, and warns when the client can only redirect to localhost. Registration
through /oauth/register works as before.
Approval is only for people who can read the project. Someone who is signed in but is not a member sees a
“No access to this project” page instead of the approval page, and nothing is redirected back to the
connector. If the approval is submitted anyway, the connector is sent back with access_denied. A
connector that was approved and then loses its project, because it was deleted or because the account
can no longer read it, is refused at the code exchange with 400 invalid_grant.
MCP_OAUTH=0 removes the flow entirely, and then only static tokens open a closed project — which also
means browser-based connectors cannot connect at all.
An Agent Skill for the tools
The repository ships an Agent Skill, skills/contextator/SKILL.md, for assistants that read the Agent Skills format. It tells
the assistant in what order to use search_docs, list_topics, read_document, whats_new and report_gap against a
Contextator MCP endpoint, to cite the file path of every passage it relies on, and to say so when the documentation does not
cover a question. It adds no tool and changes no server behaviour; the endpoint works the same with or without it.
Protocol eras
/mcp/<project-name> serves two versions of MCP on one URL. You configure nothing to choose between them.
- 2025-11-25 is the session protocol:
initialize, then anMcp-Session-Idthe server holds. Every client that existed before 0.3.0 speaks it, and every one of them keeps working, with the three changes listed at the end of this section. GET, HEAD and DELETE on the endpoint, and the legacy HTTP+SSE transport, are 2025-11-25 only. - 2026-07-28 is stateless: no
initialize, no session, and each request carries its own protocol version and client capabilities in a_metaenvelope. A client may callserver/discoverfirst to learn which protocol versions and capabilities the server offers, thentools/calldirectly. The request must repeat the protocol version in anMCP-Protocol-Versionheader and the method inMcp-Method, and ontools/call,resources/readandprompts/getthe tool name, the resource URI or the prompt name inMcp-Name(a non-ASCII value is sent as=?base64?…?=).
A request that does not carry the 2026 envelope is treated as 2025-11-25, an initialize included. A 2026 request
with a missing or contradicting header is refused with 400 and JSON-RPC code -32020, an unsupported protocol
version with 400 and -32022, one whose envelope is incomplete with 400 and -32602, and an unknown method
with 404 and -32601. A 2026 request for a project that does not exist is answered 404 / -32602.
The two eras differ in what they return, not in what they can reach: both see the same tools, resources and prompts
under the same authentication. A 2026-07-28 client always gets each tool’s outputSchema and structuredContent
(see MCP Tools), and its tools/list, resources/list and
resources/read answers carry a cache hint: ttlMs, a tenth of the time since the project last indexed
successfully, at most an hour and 0 while it is indexing, before its first index or after a failed index run, and cacheScope, public only
for a project whose access is open and private otherwise. Deleting a source, or changing the project’s access
mode, does not reset the hint, so a client can see the earlier answer for up to an hour. A 2025-11-25 answer carries
none of this. The contextator_mcp_requests_total{method,tool,era} metric shows which era your clients use.
Three things changed for 2025-11-25 clients too, with the move to version 2 of the MCP SDK, and a client that depends on
the old behaviour has to be updated: a resource that does not exist is now -32602 where it was -32002; a tool’s
input schema is JSON Schema draft 2020-12 where it was draft-07 and no longer carries execution.taskSupport; and the
validation error is worded Input validation error: Invalid arguments for tool search_docs: query: ….
Several projects at once
Add one entry per project. They stay isolated — an agent connected to both simply has two sets of tools, and a search in one never returns documents from the other.
{
"mcpServers": {
"billing-docs": { "url": "http://localhost:3444/mcp/billing" },
"mobile-docs": { "url": "http://localhost:3444/mcp/mobile" }
}
}
Connecting from another machine
- Make sure the server is reachable:
HOST=0.0.0.0(the default) and the port is open. - Use the server’s address, not
localhost:http://docs.internal:3444/mcp/demo. - Behind a reverse proxy, set
PUBLIC_BASE_URLso the dashboard prints the right URLs, and disable response buffering — see Installation.
Verifying without an agent
A smoke test ships with the repository. From a source checkout:
npm install
npm run smoke -- http://localhost:3444/mcp/demo "how do I re-index"
npm run smoke -- http://localhost:3444/mcp/demo "kurulum" --sse # exercise the legacy transport
It performs a real MCP handshake, lists the tools and runs a search. It cannot send an Authorization
header, so a project that requires a token answers it 401 — check that one with curl instead:
curl -s -i -X POST http://localhost:3444/mcp/demo \
-H "Authorization: Bearer ctxm_9f3a…" \
-H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'
If it does not connect
| Symptom | Check |
|---|---|
Unknown project "…" |
The project name in the URL, exactly as the dashboard shows it |
| The client connects but finds nothing | The project has been indexed — the dashboard shows the document and chunk counts |
| “indexed with another model” | Re-index the project (Embedding Models) |
| Works locally, not from another machine | HOST, firewall, and whether you used the machine’s address rather than localhost |
| A browser-based client is refused | Add its origin to ALLOWED_ORIGINS |
401 This project requires an MCP token |
The project is in token required mode and the client is sending no Authorization header |
401 This project requires an account-backed credential |
The project is in account required mode and the client is sending no credential at all |
401 This project requires an account-backed credential; a static token is not one |
The project is in account required mode and the client is sending a static ctxm_… token, which names nobody |
403 That account is not a member of this project |
The connector signed in as an account that is not a member of the project. This is checked in every mode, open included |
| A browser-based connector cannot connect at all | MCP_OAUTH=0 on this instance, so there is no flow for it to use |
401 Unknown, expired or revoked MCP credential |
The token was revoked, or belongs to another project, or an account credential has expired or was ended. Mint a fresh token on the project page, or reconnect the connector |
| A “No access to this project” page while approving a connector | The signed-in account is not a member of the project that connector asked for. Ask a project admin to add the account, or sign in as one that is |
400 invalid_grant at the connector’s code exchange |
The project the code was issued for no longer exists, or the account can no longer read it. Reconnect once access is restored |
More in Troubleshooting.