Connecting AI tools

Connect Claude Code, Cursor, Windsurf, or any MCP-compatible tool to your Galaxy.

Orion exposes 28 MCP tools through a dedicated MCP server at port 8787. Any tool that speaks MCP can connect.

Prerequisites

• Orion stack running (docker compose up -d)
• Health check passing: curl http://localhost:8000/health

Claude Code

claude mcp add orion --transport http http://localhost:8787/mcp

Cursor / Windsurf

Add to your MCP configuration file:

{
  "orion": {
    "url": "http://localhost:8787/mcp"
  }
}

Verify the connection

In a new conversation, ask the agent to orient:

"Call brain.orient with agent_name 'my-agent' and tell me what you see."

A successful response includes the agent's identity, galaxy context, and operating protocol. If the tool isn't available, check that the MCP endpoint is reachable at http://localhost:8787/mcp.

What's available

Namespace	Count	Purpose
memory.*	5	Knowledge storage and retrieval — works immediately, no setup
brain.*	12	Cognitive operations — orientation, thinking, recall, calibration, graph queries, synthesis, diff
sun.*	6	Steering document — read, update, working context, lessons
planet.* / biome.* / stardust.*	4	Galaxy structure inspection and record management
orion_session_end	1	Explicit session teardown

See the MCP Tools Reference for full parameter documentation and usage examples.

Troubleshooting

Tool not appearing in the AI tool's interface: Restart the AI tool after adding the MCP configuration. Some tools cache the tool list at startup.

Connection refused on 8787: Verify the MCP container is running with docker compose ps. The orion-mcp service starts after orion-api — if the API is still initializing, the MCP server waits.

Connection refused on 8000: Verify Orion is running with curl http://localhost:8000/health. If degraded lists services, those services may still be starting.

Timeout on first call: The first brain.orient after a cold start may take 1–2 seconds while caches warm. Subsequent calls return in under 30ms.