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 space UUID for memory tools.	—
`DEFAULT_SPACE_NAME`	Default space name to resolve through `/api/v1/spaces?name=`. Ignored when `DEFAULT_SPACE_ID` is set.	—
`CROSMOS_CREDENTIALS_DIR`	Directory for `credentials.json`.	`~/.crosmos`

Credential resolution

The server resolves authentication in this order:

CROSMOS_API_KEY
credentials.json created by auth login
Error if no key is available

Saved credentials live at ~/.crosmos/credentials.json unless CROSMOS_CREDENTIALS_DIR is set.

Space resolution

search_memories and add_memory need a target memory space. The MCP server resolves it in this order:

Explicit space_id passed to the tool
DEFAULT_SPACE_ID
DEFAULT_SPACE_NAME, resolved by exact name lookup
First space returned by list_spaces
Error if no spaces exist

Use DEFAULT_SPACE_ID for predictable agent behavior in production. Use 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 settings

crosmos-mcp-http reads these server variables:

Variable	Description	Default
`HOST`	Host for the HTTP server.	`0.0.0.0`
`PORT`	Port for the HTTP server.	`3000`

The HTTP server supports CORS for GET, POST, and OPTIONS, and exposes /sse, /message, and /health.

Getting Started

Concepts

MCP

SDKs

Configuration

Environment variables

Credential resolution

Space resolution

Client config with environment variables

Custom API URL

HTTP server settings

​Environment variables

​Credential resolution

​Space resolution

​Client config with environment variables

​Custom API URL

​HTTP server settings

Environment variables

Credential resolution

Space resolution

Client config with environment variables

Custom API URL

HTTP server settings