Claude Code

Preview. Claude Code is the terminal client, and it is the shortest path to a working connection on this whole tab: it takes a tgcc_ bearer key directly, so there is no OAuth flow and nothing to click.

Looking for the claude.ai connector or Claude Desktop? Those run OAuth through a settings dialog and are on Claude. This page is the CLI.

One command

claude mcp add --transport http impellabs https://api.impellabs.tech/mcp \
  --header "Authorization: Bearer tgcc_xxxxxxxxxxxx"

--transport http is not optional. Left out, Claude Code assumes stdio and tries to run your URL as a command. --header may be repeated, and -H is the short form. Check it, then use it:

claude mcp list           # impellabs  ✔ Connected
claude mcp get impellabs  # config and connection detail

List the agents in my ImpelLabs workspace and tell me which are published.

/mcp in the REPL shows the server, its tools, and its connection state.

The three scopes, and which one you want

--scope decides where the server is written and therefore who gets it. The default is local, which is the narrowest and is usually not what a team wants.

Scope	Written to	Who gets it
`local` (default)	`~/.claude.json`, under this project	You, in this project only
`project`	`.mcp.json` at the repo root	Everyone who clones the repo
`user`	`~/.claude.json`, top level	You, in every project

# Just me, just here — the default, and fine for trying it out.
claude mcp add --transport http impellabs https://api.impellabs.tech/mcp -H "Authorization: Bearer tgcc_…"

# Me, everywhere.
claude mcp add --scope user --transport http impellabs https://api.impellabs.tech/mcp -H "Authorization: Bearer tgcc_…"

# The team, via a committed file. Read the warning below first.
claude mcp add --scope project --transport http impellabs https://api.impellabs.tech/mcp \
  -H "Authorization: Bearer \${IMPELLABS_API_KEY}"

--scope project writes .mcp.json at the repo root, and that file is meant to be committed. It is the difference between everyone on the team configuring the server by hand and everyone getting it with git pull.

.mcp.json

{
  "mcpServers": {
    "impellabs": {
      "type": "http",
      "url": "https://api.impellabs.tech/mcp",
      "headers": {
        "Authorization": "Bearer ${IMPELLABS_API_KEY}"
      }
    }
  }
}

Never commit the key itself. .mcp.json expands environment variables — ${VAR} and ${VAR:-default}, in url, headers, env, command and args — and that expansion exists precisely so a shared config need not carry a secret. Each developer exports their own IMPELLABS_API_KEY; the repo carries the shape of the connection and nothing else. A tgcc_ key is a workspace credential that can spend credits.

The key inside .mcp.json is type: "http", not transport. This is the single most common mistake, because the CLI flag is --transport and the file key is not.

The first time a teammate opens a project carrying a .mcp.json, Claude Code asks them to approve the servers in it rather than connecting silently — a committed file is somebody else’s config, and it is treated that way. If you need to re-answer that prompt, claude mcp reset-project-choices clears the decision.

Or let it do OAuth

Omit the header and Claude Code discovers the flow from the server’s own metadata:

claude mcp add --transport http impellabs https://api.impellabs.tech/mcp

The server then shows as needs authentication; run /mcp in the REPL and choose Authenticate. This is the better path when you would rather not have a long-lived key on disk at all. Both paths are covered in Authentication.

Give it a key that can only do what you meant

Claude Code runs an agent loop that will iterate, and it is not shy. Its own approval prompts gate individual calls in a session; the durable control is the credential.

Mint a key per project, holding only the scopes you want an agent reaching unattended. A key with mcp:connect and agents:read cannot be talked into spending credits by any prompt, any loop or any misread tool description — that is a stronger guarantee than a prompt somebody clicks through at 6pm. Scopes never imply one another; see Authentication.

Managing it later

claude mcp list                              # every server, every scope
claude mcp get impellabs                     # one server in detail
claude mcp remove impellabs --scope project  # scope flag is optional

Two behaviours that will surprise you

Some tools answer with a job id, not a result

Extractions, reports, knowledge ingestions and jobs are queued, always. The tool returns the job id and Claude has to poll before it can honestly say the work finished. This is not a failure and it is not a timeout.

Uploading a document succeeds before it is readable

Upload returns success while parsing continues in the background. Asking for the document’s text straight afterwards returns 409 document_not_processed until parsing finishes. Claude will retry if you tell it to.

Tools

What is callable, and the scope each one demands.

Claude

The claude.ai connector and Claude Desktop, which go through OAuth.

Get started

Connect a client

Reference

One command

The three scopes, and which one you want

Or let it do OAuth

Give it a key that can only do what you meant

Managing it later

Two behaviours that will surprise you

Tools

Claude

​One command

​The three scopes, and which one you want

​Sharing one connection with the team

​Or let it do OAuth

​Give it a key that can only do what you meant

​Managing it later

​Two behaviours that will surprise you

Tools

Claude

One command

The three scopes, and which one you want

Sharing one connection with the team

Or let it do OAuth

Give it a key that can only do what you meant

Managing it later

Two behaviours that will surprise you