> ## 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.

# MCP

> Connect Crosmos to AI clients with the Model Context Protocol.

Crosmos MCP is an optional service for AI clients that support the [Model Context Protocol](https://modelcontextprotocol.io). It gives agents callable tools to search memories, add memories, list spaces, and check API health.

Use MCP when you want callable Crosmos memory tools in an AI client such as Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, opencode, Cline, Roo-Cline, Zed, or Kimi CLI. Use the [automatic-context plugins](/plugins/claude-code) when you want memory to run through a host's lifecycle, or use the [SDKs](/sdks) when you are building Crosmos into an application or backend service.

## Interactive setup

```bash theme={null}
npx @crosmos/crosmos-mcp setup
```

The setup command authenticates with your Crosmos API key, detects installed MCP clients, writes their configuration, and can install the Crosmos skill for supported AI editors.

It detects Claude Desktop, Claude Code, opencode, Cursor, VS Code, Windsurf, Cline, Roo-Cline, Zed, and Kimi CLI when they are installed.

## Authenticate manually

Generate an API key from **Settings → API Keys** in the [Crosmos Console](https://console.crosmos.dev). Keys use the `csk_` prefix.

```bash theme={null}
npx @crosmos/crosmos-mcp auth login
```

The login command validates the key and saves credentials to `~/.crosmos/credentials.json` with restricted file permissions.

<Note>
  `CROSMOS_API_KEY` overrides saved credentials. Use environment variables for CI, containers, or client configuration that should not read from `~/.crosmos`.
</Note>

## Configure a client manually

If you do not use `setup`, point your MCP client at `npx -y @crosmos/crosmos-mcp`.

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add crosmos-memory -- npx -y @crosmos/crosmos-mcp
    ```
  </Tab>

  <Tab title="Claude Desktop">
    Add to `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `~/.config/Claude/claude_desktop_config.json` on Linux, or `%APPDATA%/Claude/claude_desktop_config.json` on Windows.

    ```json theme={null}
    {
      "mcpServers": {
        "crosmos-memory": {
          "command": "npx",
          "args": ["-y", "@crosmos/crosmos-mcp"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Cursor">
    Add to `~/.cursor/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "crosmos-memory": {
          "command": "npx",
          "args": ["-y", "@crosmos/crosmos-mcp"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="opencode">
    Add to `~/.config/opencode/opencode.json`:

    ```json theme={null}
    {
      "mcp": {
        "crosmos-memory": {
          "type": "local",
          "command": ["npx", "-y", "@crosmos/crosmos-mcp"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    Add to `~/Library/Application Support/Code/User/mcp.json` on macOS, `~/.config/Code/User/mcp.json` on Linux, or `%APPDATA%/Code/User/mcp.json` on Windows.

    ```json theme={null}
    {
      "servers": {
        "crosmos-memory": {
          "command": "npx",
          "args": ["-y", "@crosmos/crosmos-mcp"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windsurf">
    Add to `~/.codeium/windsurf/mcp_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "crosmos-memory": {
          "command": "npx",
          "args": ["-y", "@crosmos/crosmos-mcp"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Kimi CLI">
    ```bash theme={null}
    kimi mcp add --transport stdio crosmos-memory -- npx -y @crosmos/crosmos-mcp
    ```
  </Tab>
</Tabs>

Restart the client after changing its MCP configuration.

## Install the skill

The setup wizard can install the Crosmos skill for supported AI editors. To install it manually:

```bash theme={null}
npx @crosmos/crosmos-mcp skill install opencode
```

See the [skill guide](/mcp/skills) for supported targets and locations.

## Next steps

<CardGroup cols={2}>
  <Card title="Tools" icon="list-check" href="/mcp/tools">
    See tool inputs, behavior, and examples.
  </Card>

  <Card title="Configuration" icon="sliders" href="/mcp/configuration">
    Configure credentials, default spaces, timeouts, and deployment settings.
  </Card>

  <Card title="GitHub repository" icon="github" href="https://github.com/crosmos-labs/crosmos-mcp">
    Browse the source code, releases, and issues.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.