Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/virsanghavi/axis/llms.txt

Use this file to discover all available pages before exploring further.

The Axis local server is a stdio MCP server that runs on your machine and exposes the full coordination toolset: job board, file locks, live notepad, project soul, and local search. It is published to npm as @virsanghavi/axis-server and can be run with a single npx command — no global install needed.
Running from a checkout is for contributing to Axis itself. Users should connect to the hosted MCP server — zero install, and new tools land server-side without needing an update.

​
Who Needs the Local Server

Use caseRecommended path
Using Axis with Claude Code, Cursor, Codex, WindsurfConnect to the hosted endpoint — no installation
MCP client that only supports stdio (not HTTP)Run npx @virsanghavi/axis-server as a bridge
Offline / air-gapped environmentsLocal server with no API key (local-only mode)
Contributing to Axis, testing changesRun from source checkout

​
Running via npx

The fastest way to use the local server. No installation step — npx downloads and runs the latest published version: 
npx -y @virsanghavi/axis-server /path/to/repo
Pass your repo path as the first argument. If omitted, the server uses the current working directory for project detection.

​
Running from Source

For contributors who have cloned the Axis repository: 
git clone https://github.com/virsanghavi/axis
cd axis
bun install
bun start:local
This compiles and runs src/local/mcp-server.ts directly. Changes you make to the source are reflected immediately on the next server restart.

​
Pointing Your MCP Client at the Local Server

Configure your MCP client to use stdio transport and invoke the local server via npx: 
{
  "mcpServers": {
    "axis": {
      "command": "npx",
      "args": ["-y", "@virsanghavi/axis-server"]
    }
  }
}
To pass a specific repo path: 
{
  "mcpServers": {
    "axis": {
      "command": "npx",
      "args": ["-y", "@virsanghavi/axis-server", "/path/to/your/repo"]
    }
  }
}
Pass environment variables through the env key in your MCP config — this is the correct production path. See Configuration for the full variable reference.

​
Required Environment Variables

Only one variable is required:
VariableDescription
AXIS_API_KEYBearer token for the hosted API. Also accepted as SHARED_CONTEXT_API_SECRET. When set, the server defaults the API URL to https://useaxis.dev/api/v1.
Without any configuration, the server runs in local/offline mode and persists all state to history/nerve-center-state.json. Coordination tools work fully; the intelligence layer (hosted search, deep_search) is unavailable.

​
Configuration Resolution Order

The local MCP server resolves configuration in this order:
1

MCP client environment (mcp.json)

Environment variables passed by the MCP client from its config file. This is the correct path for customer deployments.
2

.env.local walk

If no API key or URL is found from the client, the server walks upward from the working directory looking for a .env.local file to load. This is the local development fallback only — do not rely on it in production.
3

Defaults

With an API key but no explicit URL, the server defaults to https://useaxis.dev/api/v1. With nothing configured at all, it runs the free coordination tools in local/offline mode.

​
Local-Only vs Hosted-Only Tools

Not every tool is available on both surfaces. The local server includes tools that only make sense locally, and the hosted surface includes tools that require server-side infrastructure. Local server only:
ToolWhy local-only
guarded_writeWrites to the local filesystem through the server process
switch_projectRebinds the in-process session to a new workspace
read_contextReads from local .axis/instructions/ files
update_contextWrites to local .axis/instructions/ files
get_project_soulReads the local project soul
update_project_soulWrites the local project soul
index_fileIndexes a single local file
search_docsSearches local documentation
Hosted surface only:
ToolWhy hosted-only
deep_searchRequires server-side LLM multi-hop reasoning and embedding infrastructure

​
Circuit Breaker

When the local server is configured with an API key, it proxies coordination calls to the hosted API. If the hosted API becomes unavailable, the server does not stack timeouts or fail hard. The HTTP client wraps every hosted call in a circuit breaker:
  • Threshold: 5 consecutive 5xx or network failures open the circuit
  • Cooldown: Circuit stays open for 60 seconds
  • Fallback: While open, calls fail fast with CircuitOpenError and the server falls back to the local JSON state in history/nerve-center-state.json
  • Recovery: After the cooldown, one half-open probe is sent through; a success resets the failure counter
The practical effect is that jobs and locks keep working per-machine during a hosted outage, backed by the local JSON file. Cross-machine coordination is paused until the hosted API returns.

Build docs developers (and LLMs) love

Get started for freeTalk to us