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

# Configuration

> Configure authentication, spaces, timeouts, and deployment for the Crosmos MCP server.

The MCP server reads credentials from environment variables first, then from the saved credentials file.

## Environment variables

| Variable | Description | Default |
| - | - | - |
| `CROSMOS_API_KEY` | API key for API requests. Overrides saved credentials. | — |
| `CROSMOS_API_BASE_URL` | Crosmos API base URL. | `https://api.crosmos.dev` |
| `CROSMOS_API_TIMEOUT` | API request timeout in milliseconds. | `30000` |
| `DEFAULT_SPACE_ID` | Default memory space UUID. | — |
| `DEFAULT_SPACE_NAME` | Default memory space name. Resolved by exact name and ignored when `DEFAULT_SPACE_ID` is set. | — |
| `CROSMOS_CREDENTIALS_DIR` | Directory containing `credentials.json`. | `~/.crosmos` |

## Credential resolution

The server resolves authentication in this order:

1. `CROSMOS_API_KEY`
2. `credentials.json` created by `auth login`
3. An authentication error if no key is available

The login command validates the key against the Crosmos API before saving it. Saved credentials live at `~/.crosmos/credentials.json` unless `CROSMOS_CREDENTIALS_DIR` is set.

## Space resolution

Memory tools resolve a target space in this order:

1. An explicit `space_id` passed to the tool
2. `DEFAULT_SPACE_ID`
3. `DEFAULT_SPACE_NAME`, resolved by exact name lookup
4. The first space returned by `list_spaces`
5. An error if no spaces exist

<Tip>
  Use `DEFAULT_SPACE_ID` for predictable agent behavior in production. Use an explicit `space_id` when the agent should switch between spaces.
</Tip>

## Client config with environment variables

```json theme={null}
{
  "mcpServers": {
    "crosmos-memory": {
      "command": "npx",
      "args": ["-y", "@crosmos/crosmos-mcp"],
      "env": {
        "CROSMOS_API_KEY": "csk_...",
        "DEFAULT_SPACE_ID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    }
  }
}
```

## Custom API URL

Use `CROSMOS_API_BASE_URL` when targeting a non-default API environment:

```json theme={null}
{
  "mcpServers": {
    "crosmos-memory": {
      "command": "npx",
      "args": ["-y", "@crosmos/crosmos-mcp"],
      "env": {
        "CROSMOS_API_KEY": "csk_...",
        "CROSMOS_API_BASE_URL": "https://api.crosmos.dev"
      }
    }
  }
}
```

## HTTP server

The default MCP server uses local stdio transport. For an advanced HTTP/SSE deployment, run the separate HTTP binary:

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

Configure the listener with `HOST` and `PORT`:

| Variable | Default | Description |
| - | - | - |
| `HOST` | `0.0.0.0` | HTTP server host. |
| `PORT` | `3000` | HTTP server port. |

The server exposes:

| Route | Purpose |
| - | - |
| `/sse` | Open an MCP SSE session. |
| `/message?sessionId=...` | Send messages to an active session. |
| `/health` | Return service health. |

<Warning>
  The HTTP server enables wildcard CORS and does not provide authentication middleware. Keep it on a trusted network or put it behind an authenticated reverse proxy before exposing it publicly.
</Warning>


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