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.

400 Malformed Authorization header: expected Bearer <api-key> — the header arrives, but its value is not Bearer followed by the key. Look for a key sent without Bearer, an empty $SUBCORE_API_KEY that leaves a bare Bearer, or a ${SUBCORE_API_KEY} your client sent without expanding it.

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 that the server can reach through a deployment. Call list_agents: it reports each agent's deployment and names the problem when there is one. The usual one is an agent that names no deployment yet, which an admin links on its Connection tab in the console. Another is a deployment whose announced address nobody has approved.

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

No outcome tools, and no get_agent_models. The key lacks permissions.manageAgents. See the manage-agents permission.

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.