> For the complete documentation index, see [llms.txt](https://docs.balkan.id/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.balkan.id/balkanid-mcp/installation-and-setup/claude-code.md).

# Claude Code

Connect [Claude Code](https://code.claude.com/docs/en/mcp) to BalkanID MCP.

**OAuth is preferred.** Claude Code can also use a Bearer API key when you need Read-only access or OAuth is unavailable.

### One-tap / CLI setup (OAuth — recommended)

From a terminal:

```bash
claude mcp add --transport http balkanid https://mcp.balkanid.app/server/mcp
```

Then open a Claude Code session and run `/mcp` to complete BalkanID sign-in and consent for your tenant.

{% hint style="info" %}
OAuth currently requires **both Read and Write** scopes. See Authentication and Permissions.
{% endhint %}

You can also copy the MCP URL from **OAuth Connectors** in the [MCP UI](https://mcp.balkanid.app) and add it with the same `claude mcp add` command.

### Manual configuration (OAuth)

Add an HTTP server to your Claude Code MCP config (user or project `.mcp.json`):

```json
{
  "mcpServers": {
    "balkanid": {
      "type": "http",
      "url": "https://mcp.balkanid.app/server/mcp"
    }
  }
}
```

Run `/mcp` in Claude Code to authenticate.

### Manual configuration (API key fallback)

When you need a static Bearer token (including Read-only keys):

1. Create an API key in the [MCP UI](https://mcp.balkanid.app).
2. Add headers to the HTTP server entry:

```json
{
  "mcpServers": {
    "balkanid": {
      "type": "http",
      "url": "https://mcp.balkanid.app/server/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}
```

Do not commit tokens. Prefer environment-variable expansion if your Claude Code version supports it for MCP headers.

### Org-managed Claude Code

IT can push BalkanID MCP to all Claude Code users with `managed-mcp.json` or an allowlist. See Enterprise Rollout.

### Verify

Ask Claude Code: “Call whoami on BalkanID MCP.” You should see your email and tenant ID.

### Disable or remove

To pause the server without losing its setup, run `/mcp` and toggle `balkanid` off — its configuration is kept, and you can re-enable it later.

To sign out but keep the server configured, run `claude mcp logout balkanid` (or use **Clear authentication** in the `/mcp` panel); re-authenticate later with `claude mcp login balkanid`.

To remove the server entirely, run `claude mcp remove balkanid`. This also deletes the stored OAuth tokens and client registration for it.

### Official documentation

Anthropic documentation for MCP in Claude Code:

* [Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp) — Claude Code Docs


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.balkan.id/balkanid-mcp/installation-and-setup/claude-code.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.