Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.crosmos.dev/llms.txt

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

Get Crosmos into your AI agent in under a minute with the MCP server.

​
Prerequisites

  • An API key from the Crosmos Console (starts with csk_...)
  • Node.js 18 or later

​
Quick setup

Run the interactive setup to authenticate and install to your MCP clients in one command: 
npx @crosmos/crosmos-mcp setup
The setup walks you through:
  1. Authenticate — Enter your API key, which is validated and saved locally
  2. Install to clients — Detects installed MCP clients and writes the server config automatically
  3. Install skill — Installs the Crosmos skill into your AI editor for enhanced memory behavior
That’s it — your agent now has memory tools. Skip to client configuration if you need to customize, or see the MCP reference for tool details.

​
Install

If you prefer not to use the interactive setup, install manually:

​
Authenticate

The server resolves credentials in this order:
  1. CROSMOS_API_KEY environment variable
  2. ~/.crosmos/credentials.json (created by auth login)
  3. Error — no key found

​
Login

npx @crosmos/crosmos-mcp auth login
Prompts for your API key, validates it, and saves it to ~/.crosmos/credentials.json with restricted file permissions. To use a custom API base URL: 
npx @crosmos/crosmos/crosmos-mcp auth login --base-url https://api.crosmos.dev

​
Check status

npx @crosmos/crosmos-mcp auth status

​
Logout

npx @crosmos/crosmos-mcp auth logout
If you used setup, authentication is already configured. You can also set CROSMOS_API_KEY as an environment variable in your client config instead.

​
Configure your client

If you ran setup, your MCP clients are already configured. To add Crosmos manually, find your client below.

​
Claude Code

claude mcp add crosmos-memory -- npx -y @crosmos/crosmos-mcp

​
Claude Desktop

Add to your config file:
~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "crosmos-memory": {
      "command": "npx",
      "args": ["-y", "@crosmos/crosmos-mcp"]
    }
  }
}
Restart Claude Desktop after saving.

​
Opencode

Add to ~/.config/opencode/opencode.json: 
{
  "mcp": {
    "crosmos-memory": {
      "type": "local",
      "command": ["npx", "-y", "@crosmos/crosmos-mcp"]
    }
  }
}

​
Cursor

Add to ~/.cursor/mcp.json: 
{
  "mcpServers": {
    "crosmos-memory": {
      "command": "npx",
      "args": ["-y", "@crosmos/crosmos-mcp"]
    }
  }
}

​
VS Code

Add to your MCP config:
~/Library/Application Support/Code/User/mcp.json
{
  "servers": {
    "crosmos-memory": {
      "command": "npx",
      "args": ["-y", "@crosmos/crosmos-mcp"]
    }
  }
}

​
Windsurf

Add to ~/.codeium/windsurf/mcp_config.json: 
{
  "mcpServers": {
    "crosmos-memory": {
      "command": "npx",
      "args": ["-y", "@crosmos/crosmos-mcp"]
    }
  }
}

​
Other MCP clients

The server uses stdio transport and works with any MCP-compatible client. Point your client to npx -y @crosmos/crosmos-mcp. If you used auth login, no environment variables are needed — credentials are read from ~/.crosmos/credentials.json automatically.

​
Next steps

MCP reference

See all available tools, CLI commands, and configuration.

Memories

Learn how Crosmos structures and retrieves context.