# Connecting AI Clients

> Ready-to-paste setup for Claude Code, Cursor, Claude Desktop and any other MCP client, plus tokens, remote access and verifying an endpoint without an agent.

- Updated: 2026-11-04
- Source: https://contextator.com/en/docs/connecting-ai-clients/
- Language: en-US
- Author: Muhammet Şafak

---
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:

```bash
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:

```bash
claude mcp add --transport http demo-docs http://localhost:3444/mcp/demo
```

Check it worked:

```bash
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:

```json
{
  "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:

```json
{
  "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`:

```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:

```json
{
  "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): `POST` an `initialize` request; the session id comes
  back in the `mcp-session-id` header.
- **HTTP + SSE** (protocol `2024-11-05`, legacy): `GET` the URL; the server answers with an `endpoint`
  event pointing at `/mcp/demo/messages?sessionId=…`. It is deprecated — it keeps working, every
  response carries `Deprecation: @1790899200`, `Sunset: Sat, 02 Oct 2027 00:00:00 GMT` and a `Link` header pointing at the
  [compatibility policy](https://github.com/Contextator/Contextator/blob/main/docs/compatibility.md#legacy-httpsse), and new clients should not be set up on it. It may be removed in the first
  `1.x` minor 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 the `GET`
  that opens the stream *and* the `POST`s to `/mcp/demo/messages`, so a client that can set a header on
  only one of the two cannot connect. A browser `EventSource` is 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](/en/docs/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 an `Mcp-Session-Id` the 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 `_meta` envelope. A client may call `server/discover` first to learn which protocol
  versions and capabilities the server offers, then `tools/call` directly. The request must repeat the protocol
  version in an `MCP-Protocol-Version` header and the method in `Mcp-Method`, and on `tools/call`, `resources/read`
  and `prompts/get` the tool name, the resource URI or the prompt name in `Mcp-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](/en/docs/mcp-tools/#structured-output)), 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.

```json
{
  "mcpServers": {
    "billing-docs": { "url": "http://localhost:3444/mcp/billing" },
    "mobile-docs":  { "url": "http://localhost:3444/mcp/mobile" }
  }
}
```

---

## Connecting from another machine

1. Make sure the server is reachable: `HOST=0.0.0.0` (the default) and the port is open.
2. Use the server's address, not `localhost`: `http://docs.internal:3444/mcp/demo`.
3. Behind a reverse proxy, set `PUBLIC_BASE_URL` so the dashboard prints the right URLs, and disable
   response buffering — see [Installation](/en/docs/installation/).

:::note
**A project can be left open.** While its **MCP access** is **open**, anyone who can reach the port can
read every document indexed in it anonymously — a new project is not, by default, but can be switched
that way from its own page. Require a token or an account on the project page, keep the port on a
private network, or put authentication in front of it — see [Security](/en/docs/security/). A token is
a door of its own, naming nobody; a credential that names an account is checked against that account's
membership in every mode, **open** included.
:::

## Verifying without an agent

A smoke test ships with the repository. From a source checkout:

```bash
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:

```bash
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](/en/docs/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](/en/docs/troubleshooting/).
