Setup

The key is the one you already use for the read API. It resolves to your organization and decides which agents and tools you see. There is no second credential: the server reaches your deployments by signing its own requests, so no deployment secret ever goes into a config file.

Claude Code

claude mcp add --transport http subcore https://api.subcore.ai/mcp \
  --header "Authorization: Bearer $SUBCORE_API_KEY"

Add --scope user to make it available in every project, or --scope project to commit it for the team. Then check it:

claude mcp list

To commit the server to a repository instead, write .mcp.json at its root:

{
  "mcpServers": {
    "subcore": {
      "type": "http",
      "url": "https://api.subcore.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${SUBCORE_API_KEY}"
      }
    }
  }
}

Claude Desktop

Claude Desktop's built-in custom connectors expect the server to authenticate over OAuth. Subcore uses a static bearer token, so the connection goes through the mcp-remote bridge instead.

Open Settings → Developer → Edit Config and add:

{
  "mcpServers": {
    "subcore": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.subcore.ai/mcp",
        "--header-file",
        "/absolute/path/to/subcore-headers.txt"
      ]
    }
  }
}

with that file containing one header per line:

Authorization: Bearer sk_live_your_key_here

Then restart Claude Desktop completely — quit it, do not just close the window.

"args": ["-y", "mcp-remote", "https://api.subcore.ai/mcp", "--header", "Authorization:${AUTH_HEADER}"],
"env": { "AUTH_HEADER": "Bearer sk_live_your_key_here" }

"args": ["-y", "mcp-remote@0.8.3", "https://api.subcore.ai/mcp", "--header-file", "/absolute/path/to/subcore-headers.txt"]

Checking the connection

The server has an authenticated health endpoint that reports whether it can sign requests to your deployments:

curl -H "Authorization: Bearer $SUBCORE_API_KEY" https://api.subcore.ai/mcp/health

{
  "status": "ok",
  "organizationId": "org_...",
  "server": { "name": "subcore", "version": "0.1.0" },
  "signing": { "configured": true },
  "timestamp": 1788566920224
}

From the client, ask it to call list_agents. That is the tool to start with in any case: every other tool takes a core argument that has to be one of the slugs it returns.

Troubleshooting

401 Missing Authorization header — the header is not reaching the server. With mcp-remote, check the header file path is absolute and readable.

401 Invalid or expired API key — the URL is right and the key is not.

No conversation tools in the list, only list_agents and describe_deployment — your key reaches no agent with a published manifest. Call list_agents: it reports each agent's deployment URL and connection status, and names the problem when there is one, such as an agent whose deployment URL has not been connected in the console.

No telemetry tools — the key lacks permissions.telemetry. See authentication.

Tools that fail with "Cannot reach the deployment" — the server could not sign its request to your deployment. Check signing.configured in the health response above.