> ## Documentation Index
> Fetch the complete documentation index at: https://docs.impellabs.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code

> One command, or one committed .mcp.json that gives the whole team the same connection.

<img src="https://mintcdn.com/mahadev/-gWik8vU43pna0pu/images/harnesses/claude.svg?fit=max&auto=format&n=-gWik8vU43pna0pu&q=85&s=7832e9eacb56f571be1ddf2cad765813" alt="Claude Code" width="48" height="48" noZoom data-path="images/harnesses/claude.svg" />

**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.

<Note>
  Looking for the **claude.ai** connector or **Claude Desktop**? Those run OAuth
  through a settings dialog and are on [Claude](/connect/claude). This page is
  the CLI.
</Note>

## One command

```bash theme={null}
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:

```bash theme={null}
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            |

```bash theme={null}
# 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}"
```

## Sharing one connection with the team

`--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`.

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

<Warning>
  **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.
</Warning>

<Note>
  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.
</Note>

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:

```bash theme={null}
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](/connect/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.

<Warning>
  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](/connect/authentication).
</Warning>

## Managing it later

```bash theme={null}
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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title="Tools" icon="wrench" href="/connect/tools">
    What is callable, and the scope each one demands.
  </Card>

  <Card title="Claude" icon="https://mintcdn.com/mahadev/-gWik8vU43pna0pu/images/harnesses/claude.svg?fit=max&auto=format&n=-gWik8vU43pna0pu&q=85&s=7832e9eacb56f571be1ddf2cad765813" href="/connect/claude" width="248" height="248" data-path="images/harnesses/claude.svg">
    The claude.ai connector and Claude Desktop, which go through OAuth.
  </Card>
</CardGroup>