MCP setup

The hosted MCP server lives on the same domain as the REST API, speaks the MCP HTTP transport, and authenticates with a sub_live_... API key. There is nothing to install.

HTTP transport

Point your client at a namespace-scoped endpoint:

https://api.illumina.sh/mcp/{namespace_id}

Authenticate every request with a bearer header:

Authorization: Bearer sub_live_...

This is single-namespace mode: all 33 namespace-scoped tools operate on {namespace_id}, and the namespace-discovery tools are hidden.

Claude Code

Add the server to .mcp.json in your project root:

{
  "mcpServers": {
    "illumina": {
      "type": "http",
      "url": "https://api.illumina.sh/mcp/demo",
      "headers": {
        "Authorization": "Bearer sub_live_..."
      }
    }
  }
}

Restart Claude Code and the Illumina tools appear alongside the built-in tools. Ask it to "remember" something and it will call retain; ask what it knows and it will call recall or reflect.

Other clients

Any MCP client that supports the HTTP transport works the same way: set the URL to https://api.illumina.sh/mcp/{namespace_id} and pass the Authorization: Bearer sub_live_... header. The server answers JSON-RPC POSTs and responds to GET with a liveness probe.

Multi-namespace mode

To work across several namespaces from one connection, use the bare endpoint:

https://api.illumina.sh/mcp

Set the default namespace for the session with a header:

X-Namespace-Id: demo

In multi-namespace mode all 36 tools are exposed, and every tool accepts an optional namespace_id argument that overrides the session namespace per call — so one connection can retain into agent-alpha and recall from agent-beta, as long as the API key is scoped to both.

Key scoping

API keys are scoped to namespaces at creation, and the MCP endpoints enforce that scope on every call: connecting to a namespace outside the key's scope is refused with 403, and a per-call namespace_id override in multi-namespace mode cannot escape the scope either. See Authentication for key management.

Next steps