Skip to main content
The MCP server reads credentials from environment variables first, then from the saved credentials file.

​
Environment variables

VariableDescriptionDefault
CROSMOS_API_KEYAPI key for API requests. Overrides saved credentials.—
CROSMOS_API_BASE_URLCrosmos API base URL.https://api.crosmos.dev
CROSMOS_API_TIMEOUTAPI request timeout in milliseconds.30000
DEFAULT_SPACE_IDDefault space UUID for memory tools.—
DEFAULT_SPACE_NAMEDefault space name to resolve through /api/v1/spaces?name=. Ignored when DEFAULT_SPACE_ID is set.—
CROSMOS_CREDENTIALS_DIRDirectory for credentials.json.~/.crosmos

​
Credential resolution

The server resolves authentication in this order:
  1. CROSMOS_API_KEY
  2. credentials.json created by auth login
  3. 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:
  1. Explicit space_id passed to the tool
  2. DEFAULT_SPACE_ID
  3. DEFAULT_SPACE_NAME, resolved by exact name lookup
  4. First space returned by list_spaces
  5. 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:
VariableDescriptionDefault
HOSTHost for the HTTP server.0.0.0.0
PORTPort for the HTTP server.3000
The HTTP server supports CORS for GET, POST, and OPTIONS, and exposes /sse, /message, and /health.