Documentation

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:

CROSMOS_API_KEY
credentials.json created by auth login
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:

An explicit space_id passed to the tool
DEFAULT_SPACE_ID
DEFAULT_SPACE_NAME, resolved by exact name lookup
The first space returned by list_spaces
An error if no spaces exist

Use DEFAULT_SPACE_ID for predictable agent behavior in production. Use an explicit space_id when the agent should switch between spaces.

Client config with environment variables

{
  "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:

{
  "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:

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.

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.

Getting Started

Concepts

MCP

SDKs

Configuration

Environment variables

Credential resolution

Space resolution

Client config with environment variables

Custom API URL

HTTP server

​Environment variables

​Credential resolution

​Space resolution

​Client config with environment variables

​Custom API URL

​HTTP server

Environment variables

Credential resolution

Space resolution

Client config with environment variables

Custom API URL

HTTP server