Connect agents

Add your instance to Claude Code, Codex CLI, Cursor, OpenCode, or any MCP client.

Every instance serves one MCP server at https://<your-app-host>/mcp over Streamable HTTP. Any MCP client can connect in one of two ways:

• OAuth. Clients that support MCP OAuth need only the URL. They register themselves, and you sign in through your instance’s login page.
• Personal access token. For clients and scripts without OAuth, create a token in the dashboard under Settings → Agents and send it as Authorization: Bearer oa_pat_…. Tokens can be revoked at any time.

Setup’s agent-config step prints each snippet below with your URL filled in, and the dashboard’s Settings → Agents page shows them too. The examples use artifacts.example.com and the default server name, open-artifacts; setup names the server after its --name flag.

The snippets never contain the token itself; a token typed into a command or committed in a config file can leak through shell history or git. Codex CLI, Cursor, and OpenCode read it from the OA_TOKEN environment variable when they start, so export it, without echoing, in the shell that launches the client: read -rs OA_TOKEN; export OA_TOKEN. The setup run that mints the owner token shows it once, in the owner-token step.

Steps

1. Pick the auth method. Use OAuth if this agent’s client supports MCP OAuth. Otherwise ask the user to create a personal access token in the dashboard under Settings → Agents. Don’t run setup with --new-owner-token for this: it revokes the token the first agent uses.
2. Add the server to this agent’s MCP config, using the snippet for its client from the Connect agents doc. Name the server after setup’s --name, which defaults to open-artifacts.
3. Check the connection by calling list_artifacts.

Claude Code

read -rs OA_TOKEN
claude mcp add --transport http open-artifacts https://artifacts.example.com/mcp \
  --header "Authorization: Bearer $OA_TOKEN"
unset OA_TOKEN

read -rs takes the pasted token without showing it, so it stays out of the screen and shell history; the double quotes let the shell fill in $OA_TOKEN, and unset clears it afterwards.

Codex CLI

In ~/.codex/config.toml:

[mcp_servers.open-artifacts]
url = "https://artifacts.example.com/mcp"
bearer_token_env_var = "OA_TOKEN"

Cursor

In .cursor/mcp.json in the project, or ~/.cursor/mcp.json for every project:

{
  "mcpServers": {
    "open-artifacts": {
      "url": "https://artifacts.example.com/mcp",
      "headers": { "Authorization": "Bearer ${env:OA_TOKEN}" }
    }
  }
}

OpenCode

In opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "open-artifacts": {
      "type": "remote",
      "url": "https://artifacts.example.com/mcp",
      "enabled": true,
      "oauth": false,
      "headers": { "Authorization": "Bearer {env:OA_TOKEN}" }
    }
  }
}

Other clients

Give the client the URL https://artifacts.example.com/mcp. If it supports OAuth, that’s all it needs. Otherwise add the header Authorization: Bearer <YOUR_TOKEN>. Many clients accept this JSON, which setup prints as json. Replace <YOUR_TOKEN> with the token, and keep the file out of git:

{
  "mcpServers": {
    "open-artifacts": {
      "type": "http",
      "url": "https://artifacts.example.com/mcp",
      "headers": { "Authorization": "Bearer <YOUR_TOKEN>" }
    }
  }
}

Each version an agent publishes records the client’s name and version, or the token’s label, so you can see which agent made what.

View as Markdown