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 identifies you in one of two ways — use whichever your client supports.

1. Sign in with your ByteTree account (recommended, no key). Point your client at the endpoint above with no credentials. On first use it opens ByteTree sign-in in your browser; approve access once and the client handles it from then on — nothing to paste, nothing to rotate. This is the simplest path for Claude, ChatGPT, Claude Code, and any other client that connects by URL.

2. A ByteTree API key. Send your key as a bearer token — for service accounts, CI, or clients without interactive sign-in:

Authorization: Bearer <your-api-key>

Keys are issued per customer and are revocable individually. Keys are also 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.

Either way, access resolves to your ByteTree account and needs a plan that includes MCP — the api+mcp capability described on the Authentication page. A view-only account, or a key without that capability, is refused with a 403. Access is re-checked on every request, so a plan change takes effect immediately.

Signed in but got 403? Sign-in worked and we know who you are — your account’s plan just doesn’t include MCP yet. That is a different thing from a sign-in failure; contact ByteTree to add MCP to your plan.

Response codes

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 your plan. Only 401 is worth re-checking a key value for.

Client configuration

ByteTree MCP speaks Streamable HTTP natively, so any MCP client that connects by URL can use it: add https://mcp.bytetree.io/mcp as a remote (or “custom”) MCP server and sign in when prompted — no key, no bridge.

The clients below are the ones we’re asked about most; anything else that supports remote MCP servers with OAuth works the same way. Key-based and stdio-only setups are covered further down.

Claude (claude.ai and Desktop) — sign in, no key

Custom remote connectors are added the same way on both: Customize → Connectors → + → Add custom connector, paste https://mcp.bytetree.io/mcp, and add it. Complete ByteTree sign-in when prompted. No bridge, no key.

If your organisation manages connectors, an owner adds it once under Organization settings → Connectors → Add → Custom, and members then connect individually.

Leave “Advanced settings” empty. No OAuth client ID or secret is needed — those fields are for pre-registered app credentials, and ByteTree MCP signs you in on its own.

Anthropic documents the current steps and screens in Get started with custom connectors using remote MCP.

ChatGPT — sign in, no key

Add ByteTree MCP as a custom connector with the URL https://mcp.bytetree.io/mcp, then complete ByteTree sign-in when prompted.

Custom MCP connectors are a ChatGPT Business, Enterprise or Edu feature on ChatGPT web, and a workspace admin or owner has to switch on developer mode before anyone can add one — so this route isn’t open on personal Plus or Pro accounts. OpenAI documents where that toggle lives, and the steps for adding a server by URL, in Developer mode and MCP apps in ChatGPT.

Claude Code — sign in, no key

claude mcp add --transport http bytetree https://mcp.bytetree.io/mcp

Then authenticate once: run /mcp inside Claude Code and pick the server (it lists as needing authentication), or run claude mcp login bytetree from the shell. Either opens ByteTree sign-in in your browser; approve it and you’re connected. No --header, no key.

Add --scope user if you want the server available in every project rather than just this one.

Any other MCP client

If it supports remote MCP servers over Streamable HTTP with OAuth, point it at https://mcp.bytetree.io/mcp and sign in — no key. Any client that lets you set request headers can send Authorization: Bearer <your-api-key> instead. For stdio-only clients, use the mcp-remote invocation under With an API key instead, with your key.

With an API key instead

For service accounts, CI, and clients without interactive sign-in.

In Claude Code, 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 with a key (rather than sign-in) needs the mcp-remote 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>"
    ]
  }
}
}

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

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.

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 your credentials are getting through as well, invoke summarise_dataset — it also has no inputs, but it reaches the data plane, so a successful call proves you were accepted end to end.

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

1. 401 — the credentials that reached us weren’t ones we could validate. What to check depends on how you configured it:

   • Signed in, no key — there is no key value to check: reconnect, or re-run the sign-in.
   • claude mcp add with a key, 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 credential is fine and MCP just isn’t enabled on your plan. Contact ByteTree to have the api+mcp capability added; re-checking a key value won’t help.

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

Next steps

• Tool Reference — every tool, schema, and response shape.
• Concepts — vocabulary the tools and glossary share.