axisdream-mcp

Run Axisdream in two MCP modes:

• Local stdio for Claude Desktop, Cursor, Codex, VS Code, and other local MCP hosts
• Hosted Streamable HTTP for ChatGPT, Claude web connectors, and other remote MCP clients

Published on npm as axisdream-mcp (separate from the axisdream SDK package). If you are inside the Axisdream web app, use the Integrations page first; it generates host-specific setup for all spaces or a preferred starting space.

Local usage

npx -y [email protected] --api-key cs-YOUR_KEY --base-url https://your-axisdream-api.example

Or via environment variables:

export AXISDREAM_API_KEY=cs-YOUR_KEY
export AXISDREAM_BASE_URL=https://your-axisdream-api.example
npx -y [email protected]

To start in one space, add --space my-agent or AXISDREAM_SPACE=my-agent.

Hosted remote MCP

Axisdream also supports hosted MCP over Streamable HTTP. In production, web chatbot connectors should use the hosted server URL instead of running npx locally:

https://axisdream.xyz/mcp

Remote MCP uses OAuth bearer tokens, not AXISDREAM_API_KEY. End users connect through the Axisdream consent flow, and the hosted MCP surface stays aligned with the same 11 curated tools exposed by local MCP.

In production, hosted Axisdream MCP does not accept API-key bearer auth. API keys remain for local stdio connections only.

Hosted remote MCP also applies lightweight prototype limits:

• unauthenticated probes: 40/min/IP
• authenticated traffic: 120/min/account
• authenticated traffic: 300/min/IP

Claude Desktop setup

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "axisdream": {
      "command": "npx",
      "args": [
        "-y",
        "[email protected]"
      ],
      "env": {
        "AXISDREAM_API_KEY": "cs-YOUR_KEY",
        "AXISDREAM_BASE_URL": "https://your-axisdream-api.example",
        "AXISDREAM_SPACE": "my-agent"
      }
    }
  }
}

Restart Claude Desktop. The Axisdream tools are now available.

What is axisdream-mcp?

axisdream-mcp is the official curated MCP wrapper. It keeps the tools available to your MCP host aligned with the Axisdream platform across both local and hosted connections.

Before MCP initialization, a preferred-space connection also reads that space's capabilities. If the space is still onboarding, the wrapper returns the platform-owned Onboarding Directive through standard MCP instructions and publishes only the onboarding-safe tool subset. The connected agent should ask the one setup question first, then create initial knowledge/, memory/, and compact state/ context only. It must not create skills during onboarding.

• axisdream (Python or TypeScript SDK) — Direct API client for programmatic access
• axisdream-mcp — MCP protocol bridge for local hosts and hosted remote MCP clients

If you're building an application, use the axisdream SDK directly. If you're connecting an MCP host, use axisdream-mcp or the hosted /mcp URL.

Dynamic Tools

| Tool | Description | |---|---| | retrieve | Ranked context discovery across semantic, lexical, and relationship signals. | | list_spaces | List accessible spaces and IDs. | | add | Full-file add or replace with automatic indexing across all layers | | list | Inspect folders and paths for an explicit structure request | | list_skills | Discover procedural skills without loading their bodies. | | get_skill | Load one or more complete exact skill Markdown files. | | fetch | Read identified knowledge, memory, or state files. | | forget | Delete knowledge from all layers | | update | Targeted write: append, field_update, or replace | | update_confidence | Update confidence score on a file | | get_related_files | Get knowledge graph neighbors of a file |

axisdream-mcp now exposes the same canonical 11-tool taxonomy as the REST API and SDKs. The old public tool names are not exposed by the MCP wrapper.

Search options

retrieve parameters (enforced at backend). The backend coordinates the retrieval sources automatically; limits adjust candidate coverage:

| Parameter | Type | Default | Range | Description | |---|---|---|---|---| | query | string | — | — | What to search for | | top_k | number | 10 | 1–20 | Final accepted context chunks. Axisdream coordinates all retrieval layers automatically. | | bucket | string | — | knowledge/memory/state | Filter indexed hybrid-search corpus. | | folder_path | string | — | — | Restrict to folder. | | query_variants | array | yes | exactly 3 | Agent-generated {query, kind} probes: exactly one rewrite, one exact, and one hyde; the top-level query is raw. |

Examples:

retrieve(query="retry logic", top_k=10)
retrieve(
  query="design the onboarding modal",
  query_variants=[
    {query="modal composition and hierarchy", kind="rewrite"},
    {query="accessible onboarding dialog behavior", kind="exact"},
  ],
  top_k=10,
)

For a simple request, send one focused query. For a multi-aspect request, let the connected model create no more than three focused variants in the same call. Axisdream fuses and deduplicates them under the requested global limits; the agent should fetch only the returned files that materially affect the task.

Options

| Flag | Env var | Default | Description | |---|---|---|---| | --api-key | AXISDREAM_API_KEY | required for stdio | Axisdream API key for local MCP hosts | | --space | AXISDREAM_SPACE | optional | Preferred starting space name or ID | | --base-url | AXISDREAM_BASE_URL | http://localhost:8000 | Backend URL | | --transport | AXISDREAM_MCP_TRANSPORT | stdio | MCP transport: stdio or http | | --host | AXISDREAM_MCP_HOST | 127.0.0.1 | HTTP bind host when --transport http | | --port | AXISDREAM_MCP_PORT | 8787 | HTTP bind port when --transport http |

Local-first note

For local development, omit --base-url to use http://localhost:8000.