Connect an AI assistant to Cairn
Copy one address, paste it into your assistant, sign in to Cairn and approve. That is all. It works with Claude, ChatGPT, Cursor, VS Code and Claude Code, and you install nothing.
If you are an AI agent, also read Rules for AI agents.
1. Copy the connector URL
Your Cairn server's connector URL is your portal address followed by /mcp:
https://cairn.example.com/mcp
The portal shows it with a Copy button: open any project, go to Monitoring, then AI agents, and look at Connect an AI assistant.
2. Paste it into your assistant
Claude (claude.ai and Claude Desktop)
- Open Customize, then Connectors.
- Select Add, then Add custom connector.
- Name it
Cairn, paste the connector URL and select Continue. - Keep the detected sign-in settings and select Add. Sign in to Cairn when asked.
- In a chat, turn the connector on from the + menu, under Connectors.
On Team and Enterprise plans an owner adds the connector once in Organization settings, Connectors. Each person then connects from Customize, Connectors.
ChatGPT (web)
- Open
chatgpt.com/pluginsand select Add custom MCP server. - Name it
Cairnand paste the connector URL as the Server URL. - Choose OAuth for authentication, confirm the warning, and sign in to Cairn when asked.
Your workspace settings may need to allow custom MCP servers.
Cursor
Add this to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json for every project:
{
"mcpServers": {
"cairn": { "url": "https://cairn.example.com/mcp" }
}
}
Cursor asks you to sign in. Approve the connection in the browser.
VS Code (GitHub Copilot chat)
Run MCP: Add Server from the command palette, choose HTTP and paste the connector URL. Or add this to .vscode/mcp.json:
{
"servers": {
"cairn": { "type": "http", "url": "https://cairn.example.com/mcp" }
}
}
Start the server when VS Code offers it, then sign in to Cairn.
Claude Code
claude mcp add --transport http cairn https://cairn.example.com/mcp
Then type /mcp in Claude Code, pick cairn and sign in in the browser.
3. Sign in and approve
Your browser opens the Cairn sign-in page, then a screen that shows:
- the name the assistant gave itself, and the address you go back to afterwards. Only continue if you started this connection;
- what the assistant may do. Read-only permissions are ticked. Permissions that change things, such as running commands, are not ticked. Permissions your role does not have are greyed out.
Select Approve. If your account uses two-factor sign-in, Cairn asks for a code from your authenticator app the first time you approve an assistant, and again if you give it more permissions.
Ask the assistant: "Check Cairn health and list my projects."
What the assistant can do
- It acts as you, with only the permissions you ticked, and never more than your role allows. If your role is lowered later, the assistant loses those permissions at once.
- It sees only the projects you can see.
- Destructive commands, such as deleting or scaling, wait in Waiting for approval on the AI agents view until a person approves them.
- It cannot approve commands, deploy, or change users, tokens or settings.
| Permission | Who can grant it |
|---|---|
| See your projects, Read logs | everyone |
| Read the audit log | Admin, DevOps, Tech lead |
| See nodes and pods, See install status | Admin, DevOps |
| Check commands against the policy | Admin, DevOps, Tech lead |
| Run allowed commands | Admin, DevOps |
Disconnect an assistant
On the AI agents view, under Connected assistants, select Disconnect. The assistant stops working right away. Admins and DevOps see and can disconnect every assistant on the platform. Everyone else sees their own.
Troubleshooting
| Symptom | Check |
|---|---|
| The assistant says it cannot reach the server | Open https://<your-domain>/.well-known/oauth-protected-resource in a browser. It should show JSON. If it shows the portal, upgrade Cairn so the ingress sends /mcp to the API. |
| "Remote MCP is not available" | The server has no public domain configured. Install or upgrade with a domain. |
| The sign-in window says the request is not valid | Remove the connector and add it again, so the assistant registers afresh. |
| You are asked for a code on approve | Your account has two-factor sign-in. Enter the code from your authenticator app. |
A tool answers 403 |
The assistant lacks that permission, or your role does not allow it. Disconnect and connect again to grant more. |
A tool answers 401 |
The connection was disconnected or expired. Connect again. |
Use an agent token instead
For scripts and clients that cannot sign in through a browser, send an agent token as a bearer header to the same connector URL.
- Create a token on the AI agents view, under Agent tokens (Admin or DevOps, with two-factor sign-in). Copy the
plat_agent_...value. It is shown once. - Configure the client with the header
Authorization: Bearer plat_agent_.... For example, in Cursor:
{
"mcpServers": {
"cairn": {
"url": "https://cairn.example.com/mcp",
"headers": { "Authorization": "Bearer ${env:CAIRN_AGENT_TOKEN}" }
}
}
}
An agent token is not tied to a person: with Read every project it sees every project. Revoke it under Agent tokens.
Run the MCP server locally
You can also run the MCP server on your own computer and let your AI tool start it. It offers two extra tools the remote endpoint does not: platform_login for approving commands from the assistant, and platform_deploy.
From a copy of the Cairn repository:
cd platform/mcp-server
npm install
npm run build
You need Node.js 18 or later. Then add it to your AI tool. The AI agents view shows this config with your server address filled in:
{
"mcpServers": {
"platform": {
"command": "node",
"args": ["/absolute/path/to/SERVER-automation/platform/mcp-server/dist/index.js"],
"env": {
"PLATFORM_URL": "https://cairn.example.com",
"PLATFORM_AGENT_TOKEN": "plat_agent_..."
}
}
}
}
Replace the path in args with the real absolute path to dist/index.js.
| Variable | Meaning |
|---|---|
PLATFORM_URL |
Your server address, with or without /api. Default: http://localhost:3000. |
PLATFORM_AGENT_TOKEN |
The plat_agent_... token. |
PLATFORM_MCP_TIMEOUT_MS |
Time limit for one API call. Default 15000 (15 s). |
PLATFORM_MCP_LONG_TIMEOUT_MS |
Time limit for running a command or a deploy. Default 90000 (90 s). |
Test from a terminal (health does not need a token):
cd platform/mcp-server
PLATFORM_URL=https://cairn.example.com npm run smoke
Approve a risky command
In the portal (easiest): open a project, go to Monitoring, then AI agents. Under Waiting for approval, check the command and select Approve or Reject. Then tell the assistant to run it again with the approval.
From the local server: call platform_login with your email and password, then platform_list_pending_commands and platform_approve_command. This only works for accounts without two-factor sign-in, because platform_login cannot enter a code. Never put your password in the config file.
An agent token or a connected assistant cannot list, approve or reject requests. An approval lasts one hour and works only for the token or assistant that asked.
Deploy from an assistant
platform_deploy needs a person's session, so it is only on the local server. Run it without PLATFORM_AGENT_TOKEN and call platform_login first, with an account that has the Developer, Tech lead, DevOps or Admin role and no two-factor sign-in. Otherwise deploy from the portal.
How it works
- The connector URL is a remote MCP endpoint served by the Cairn API (Streamable HTTP). Sign-in follows the MCP authorization standard: OAuth 2.1 with PKCE, automatic client registration, and tokens that only work for this endpoint.
- Access tokens last one hour (
MCP_ACCESS_TOKEN_TTL_SEC). The assistant renews them with a refresh token that can be used once; an unused connection expires after 30 days (MCP_REFRESH_TOKEN_TTL_SEC). Cairn stores only hashes of these tokens. - Assistants that register but are never approved are removed after an hour. Registration is rate limited, and each address can hold only a few unapproved registrations at a time.
- Every connection, approval, disconnect and tool call is written to the audit log.
- The server's public address comes from its configured domain (
DOMAIN, orMCP_PUBLIC_URLto override). Without one, the remote endpoint stays off. - Tool results pass through a redaction step that removes tokens, passwords and other secrets before the assistant sees them.
For developers / API
| Method | Path | Who can call it |
|---|---|---|
| POST | /mcp |
connected assistant (OAuth access token) or agent token |
| GET | /.well-known/oauth-protected-resource/mcp |
anyone |
| GET | /.well-known/oauth-authorization-server |
anyone |
| POST | /api/oauth/register |
anyone (rate limited) |
| POST | /api/oauth/token, /api/oauth/revoke |
registered assistant |
| GET | /api/mcp/connections |
person: own connections; Admin, DevOps: all |
| DELETE | /api/mcp/connections/:id |
person: own; Admin, DevOps: any |
| GET | /api/health, /api/openapi.json |
anyone |
| GET | /api/agent-tokens/me |
agent token or person |
| GET | /api/agent-tokens |
person: Admin, DevOps |
| POST | /api/agent-tokens |
person: Admin, DevOps, with a recent second factor |
| GET, PATCH, DELETE | /api/agent-tokens/:id |
person: Admin, DevOps |
| POST | /api/agent/commands/validate |
agent token or assistant with commands:validate, or person: Admin, DevOps, Tech lead |
| POST | /api/agent/commands/execute |
agent token or assistant with commands:execute, or person: Admin, DevOps |
| GET | /api/agent/commands/pending |
person only: Admin, DevOps, Tech lead |
| POST | /api/agent/commands/:id/approve, /reject |
person only: Admin, DevOps |
Create an agent token without the portal. The login session must carry a fresh second factor:
PLATFORM_URL=https://cairn.example.com
CHALLENGE=$(curl -sS -X POST "$PLATFORM_URL/api/auth/login" \
-H 'Content-Type: application/json' \
-d '{"email":"[email protected]","password":"YOUR_PASSWORD"}' | jq -r .challengeToken)
TOKEN=$(curl -sS -X POST "$PLATFORM_URL/api/auth/mfa/challenge" \
-H 'Content-Type: application/json' \
-d "{\"challengeToken\":\"$CHALLENGE\",\"code\":\"123456\"}" | jq -r .token)
curl -sS -X POST "$PLATFORM_URL/api/agent-tokens" \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"name":"laptop-cursor"}'
The 201 response contains token once. Optional body fields: scopes (array) and expiresAt (date). If you send no scopes, the token gets commands:validate, commands:execute, projects:read, logs:read, cluster:read, audit:read, bootstrap:read. replays:read is never in the default set.