Installation

Prerequisites

• Node.js 18 or newer — nodejs.org.
• Git — for cloning the repository.
• npm — bundled with Node.js.

An active SkySpark instance is optional but unlocks the execution, sync, and live-query features once you connect one.

Clone and build

git clone https://github.com/Project-SandStar/axon-mcp-server.git
cd axon-mcp-server

# Install dependencies
npm install

# Compile TypeScript to JavaScript
npm run build

The build emits to dist/. If you see TypeScript errors, confirm your Node version is 18+ with node --version.

First-time database initialisation

The admin dashboard and user store persist to SQLite via Prisma. Run the initial migration once:

npx prisma migrate deploy

This creates .data/app.db and seeds an initial admin account. Default credentials: admin / admin — change the password immediately on first login.

Start the server

Stdio mode (for local MCP clients)

The default. AI clients like Claude Desktop spawn the server as a subprocess and communicate over stdin/stdout.

npm start

HTTP mode (for remote MCP clients + the admin dashboard)

MCP_TRANSPORT=http MCP_PORT=3847 npm start

• MCP endpoint: http://localhost:3847/mcp
• Admin dashboard: http://localhost:3847/admin
• OAuth endpoints: http://localhost:3847/oauth/*

Wire it into your MCP client

For Claude Desktop, add a block to claude_desktop_config.json:

{
  "mcpServers": {
    "axon": {
      "command": "node",
      "args": ["/absolute/path/to/axon-mcp-server/dist/index.js"],
      "env": {
        "AXON_CONFIG": "/absolute/path/to/axon-config.json"
      }
    }
  }
}

Restart the client. The axon tool set should appear in the tool picker.

Verify it works

With the server running, the first searchAxonExamples call triggers the initial code + docs indexing pass. Expect 30–60 seconds the first time; subsequent restarts load the cached index in under a second.

If you see INDEX_NOT_FOUND errors, check that codePath and docsPath in your config point to directories that actually contain .axon / .html files.