Getting Started with ByteTree MCP

Endpoint

ByteTree MCP is served from:

https://mcp.bytetree.io/mcp

POST /mcp is the Streamable HTTP MCP transport — the only authenticated endpoint. GET and DELETE on /mcp return 405 with an Allow: POST header: this transport is JSON-only and offers neither an SSE stream nor a session lifecycle, so there is nothing for those methods to do.

Two liveness probes are exposed outside auth: GET / returns ByteTree MCP (plain text), and GET /health returns { service: "bytetree-mcp", status: "ok", timestamp: <iso> }.

Authentication

ByteTree MCP takes your own ByteTree API key, sent as a standard bearer token:

Authorization: Bearer <your-api-key>

Keys are issued per customer and are revocable individually. The key must carry the api+mcp capability, described on the Authentication page. What you can read through MCP is exactly what your key’s scope allows, enforced on every request rather than only when the client connects.

A key that works against the REST API is not on its own proof that MCP is enabled on it. If MCP isn’t enabled, you’ll get a 403 — that response means precisely this and nothing else.

Keys are environment-specific. A key issued against one ByteTree environment will not authenticate against another, so make sure the key you configure was issued for the endpoint above.

Response codes

CodeMeaning
401No key was sent, or the key could not be validated.
403The key is valid but is not provisioned for MCP access — it lacks the api+mcp capability. Nothing is wrong with the key itself; it needs MCP enabled.
405Sent on GET or DELETE. The endpoint is POST-only — see Endpoint.
503We could not verify your key right now. This is a temporary fault on our side, not a signal to rotate credentials — retry shortly.

The 401/403 split is deliberate: 401 means the credential didn’t check out, 403 means it did and MCP simply isn’t enabled on it. Only 401 is worth re-checking the key value for.

Client configuration

ByteTree MCP speaks Streamable HTTP natively. Clients that support that transport can connect straight to it; clients that only speak stdio need the mcp-remote bridge.

Claude Code

Claude Code speaks the transport natively, so no bridge is needed. Let the CLI write the config:

claude mcp add --transport http bytetree https://mcp.bytetree.io/mcp \
--header "Authorization: Bearer <your-api-key>"

Pass the real key on the command line — the CLI writes it into your config, so no placeholder is involved and the expansion trap below never arises.

To write the stanza by hand instead, add it to .mcp.json in your project root (shareable with the team) or ~/.claude.json (user-scoped, all projects):

{
"mcpServers": {
  "bytetree": {
    "type": "http",
    "url": "https://mcp.bytetree.io/mcp",
    "headers": {
      "Authorization": "Bearer ${BYTETREE_MCP_KEY}"
    }
  }
}
}

"type" is required. A stanza with a url and no type is read as a stdio server, and the entry is skipped as a configuration error rather than connecting. Use "http" ("streamable-http" is accepted as an alias).

Claude Code expands ${VAR} references itself when it reads these files, so the placeholder above works as written — set BYTETREE_MCP_KEY in your environment.

Claude Desktop

Claude Desktop needs the stdio bridge. Paste this into the mcpServers block of the platform-specific config file:

{
"mcpServers": {
  "bytetree": {
    "type": "stdio",
    "command": "npx",
    "args": [
      "-y",
      "mcp-remote",
      "https://mcp.bytetree.io/mcp",
      "--header",
      "Authorization: Bearer <your-api-key>"
    ]
  }
}
}

Important — the most common setup failure. ${VAR} references are expanded by the client itself, and not every client does it. Claude Desktop expands nothing, and as a GUI app it doesn’t read your shell profile either — so launching it from a terminal or exporting the variable more forcefully will not help.

Write the actual key into the Claude Desktop config, as shown above. If you paste a ${...} placeholder, that literal string is sent as your key and you get a 401 that explains nothing.

Claude Desktop reads this file only at startup — quit and relaunch the app after editing. Saving and waiting for a reload leaves the old config in force.

Other MCP clients

Point a natively-capable client at https://mcp.bytetree.io/mcp with the same Authorization: Bearer header. For stdio-only clients, use the mcp-remote invocation shown in the Claude Desktop block above, substituting your own key.

Verifying the connection

Once configured, your client should list ByteTree MCP among its available servers and surface up to 14 tools — the 13 data tools plus ping — along with the bytetree://glossary resource. Fourteen is what the server offers; you’ll see fewer if your client has individual tools switched off. ping takes no inputs and returns pong with a server timestamp; it’s the cheapest check that the transport is wired up at all.

To confirm the auth header is getting through as well, invoke summarise_dataset — it also has no inputs, but it reaches the data plane, so a successful call proves your key was accepted end to end.

If a tool call returns an auth error, work down the response code you got:

  1. 401 — the key that reached us wasn’t one we could validate. What to check depends on how you configured it:

    • claude mcp add, or a key pasted into Claude Desktop — the key sits in the config file itself, so check it was pasted whole, without truncation or stray quotes. No environment variable is involved in either of these routes.
    • A hand-written stanza using ${BYTETREE_MCP_KEY} — check the variable is set in the environment the client launches from (its own launcher, not the shell where you type), and that your client expands ${VAR} at all. Claude Desktop does not.

    A key issued for a different ByteTree environment also returns 401.

  2. 403 — the key is fine and MCP just isn’t enabled on it. Contact ByteTree to have the api+mcp capability added; re-checking the key value won’t help.

  3. 503 — transient on our side. Retry shortly; don’t rotate the key.

Next steps