cogspace-mcp

Run Cogspace as a local MCP server — plug any space into Claude Desktop, Cursor, Windsurf, or any MCP-compatible host.

Published on npm as cogspace-mcp (separate from the cogspace SDK package).

Usage

npx cogspace-mcp --api-key local-dev-token --space my-agent

Or via environment variables:

export COGSPACE_API_KEY=local-dev-token
export COGSPACE_SPACE=my-agent
npx cogspace-mcp

Claude Desktop setup

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

{
  "mcpServers": {
    "cogspace": {
      "command": "npx",
      "args": [
        "cogspace-mcp",
        "--api-key",
        "local-dev-token",
        "--space",
        "my-agent",
        "--base-url",
        "http://localhost:8000"
      ]
    }
  }
}

Restart Claude Desktop. The Cogspace tools are now available.

What is cogspace-mcp?

cogspace-mcp is the official curated MCP wrapper. It acts as a thin first-party adapter: it fetches public tool schemas from GET /tools and authenticated runtime dispatch metadata from GET /tools/runtime, so the platform remains the source of truth for both tool shape and routing.

• cogspace (Python or TypeScript SDK) — Direct API client for programmatic access
• cogspace-mcp — MCP protocol bridge for agent tool calling (Claude Desktop, Cursor, etc.)

If you're building an application, use cogspace SDK directly. If you're using Claude Desktop, use cogspace-mcp.

Dynamic Tools

| Tool | Description | |---|---| | cogspace_search_hybrid | Unified search: vectors + BM25 + knowledge graph. Control per-source limits. | | cogspace_add | Full-file add or replace with automatic indexing across all layers | | cogspace_list | List files in a folder — always call this first | | cogspace_retrieve | Get one file with full content | | cogspace_forget | Delete knowledge from all layers | | cogspace_update | Targeted write: append, field_update, or replace | | cogspace_update_confidence | Update confidence score on a file | | cogspace_get_related_files | Get knowledge graph neighbors of a file | | cogspace_suggest_metadata | Suggest type/topic/related for new content |

cogspace-mcp now exposes the same canonical 10-tool taxonomy as the REST API and SDKs. Compatibility aliases like /read and /write are still available in the backend for older clients, but they are not the primary contract.

Search options

cogspace_search_hybrid parameters (enforced at backend):

| Parameter | Type | Default | Range | Description | |---|---|---|---|---| | query | string | — | — | What to search for | | vector_limit | number | 100 | 0–100 | Max vector results. 0 = skip vectors. | | bm25_limit | number | 100 | 0–100 | Max keyword results. 0 = skip BM25. | | kg_limit | number | 100 | 0–100 | Max graph neighbors. 0 = skip KG. | | layer | string | — | expertise/memory/root | Filter by layer. | | folder_path | string | — | — | Restrict to folder. |

Examples:

cogspace_search_hybrid(query="retry logic", vector_limit=10, bm25_limit=10)
cogspace_search_hybrid(query="error", bm25_limit=0)  // vector-only
cogspace_search_hybrid(query="timeout", vector_limit=0)  // keyword-only

Options

| Flag | Env var | Default | Description | |---|---|---|---| | --api-key | COGSPACE_API_KEY | required | API key or any non-empty local-dev token | | --space | COGSPACE_SPACE | required | Space name or ID | | --base-url | COGSPACE_BASE_URL | http://localhost:8000 | Backend URL |

Local-first note

If your local backend has auth disabled, keep --api-key anyway and use any non-empty placeholder.