Connect Claude Code to Axis — OAuth and API Key Setup

Claude Code connects to Axis over HTTP MCP, so there is no wrapper process or local server to run. Add the hosted endpoint once and every project you open from that point shares the same connection — Axis detects which repo is active from file paths in tool arguments and rebinds automatically without a restart.

Add Axis via the CLI

OAuth (Recommended)
API Key

Run the following command in your terminal. The --scope project flag writes the server into the current repo’s .claude/ config rather than your global profile, so it travels with the repository.

claude mcp add --scope project --transport http axis https://useaxis.dev/api/mcp

Authenticate

Open the MCP panel inside Claude Code and trigger the OAuth flow:

claude /mcp

Select axis from the server list, click Authenticate, and complete the browser login. Axis issues a rotating refresh token — you will not need to log in again unless you explicitly revoke access.

Pass your API key as an Authorization header. This is useful for CI runners, shared machines, or anywhere you prefer not to go through a browser flow.

claude mcp add --transport http axis https://useaxis.dev/api/mcp \
  --header "Authorization: Bearer sk_sc_your_key"

Do not commit your API key. If you use --scope project, the key is written into .claude/mcp.json — add that file to .gitignore or use a secret manager and pass the header at runtime instead.

Add Axis via config file

If you prefer to manage MCP servers by editing config directly, create or update .claude/mcp.json at the repo root (project scope) or ~/.claude/mcp.json (global scope):

OAuth (Recommended)
API Key

Omit headers entirely. Claude Code will present an Authenticate button on the server entry and open the browser flow on first use.

{
  "mcpServers": {
    "axis": {
      "type": "http",
      "url": "https://useaxis.dev/api/mcp"
    }
  }
}

{
  "mcpServers": {
    "axis": {
      "type": "http",
      "url": "https://useaxis.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer sk_sc_your_key"
      }
    }
  }
}

Workspace switching

Axis detects the active repository from two sources, in order of priority:

The AXIS_WORKSPACE_ROOT environment variable — set this in a per-repo .env or your shell profile when you want a stable override.
Absolute file paths in tool call arguments — Axis inspects paths like /Users/you/projects/acme/src/auth.ts and derives the repo root automatically.

When either source changes mid-session, the server rebinds in-process and notes the switch in the tool response. No restart is needed when switching repos. Jobs, locks, and the live notepad all switch to match the new project.

First action: `get_project_soul`

Per the agent protocol, the first thing any connected agent does on a new task is call get_project_soul. This loads the project’s goals, conventions, and current coordination state so the agent never starts blind. Claude Code triggers this automatically when Axis tools are present — you do not need to prompt it.

Claude Code is detected automatically for session transcripts. Axis captures the complete tool timeline even when chat history is private.

Get Started

Connecting Agents

Core Features

Teams & Orgs

Self-Hosting

Connect Claude Code to Axis — OAuth and API Key Setup

Add Axis via the CLI

Add Axis via config file

Workspace switching

First action: `get_project_soul`

Build docs developers (and LLMs) love

Get Started

Connecting Agents

Core Features

Teams & Orgs

Self-Hosting

Documentation Index

​Add Axis via the CLI

​Add Axis via config file

​Workspace switching

​First action: get_project_soul

Build docs developers (and LLMs) love

Add Axis via the CLI

Add Axis via config file

Workspace switching

First action: `get_project_soul`