Connect Alumia via MCP

Drive Alumia from Claude Desktop, Codex, Gemini, or any MCP-aware client.

Alumia ships a hosted Model Context Protocol (MCP) server so any MCP-aware client (Claude Desktop, Cursor, Codex CLI, Gemini CLI, custom agents) can list, inspect, and operate on resources inside your Alumia organization.

Two transports are supported:

Streamable HTTP — point the client at https://app.alumia.com/mcp with a Bearer header. No install.
stdio — run the @hasna/alumia CLI MCP server (alumia mcp --stdio) and let the client spawn it. The stdio server exposes a broader automation surface (alumia_exec, billing, tasks, schedules, webhooks, knowledge search, and more) than the hosted HTTP server — see Terminal CLI.

Org-registered MCP servers for in-product agents are documented at MCP servers API. REST API calls use https://alumia.com/api/v1; the hosted MCP endpoint uses app.alumia.com.

1. Create an API key

Open /<orgSlug>/developers → API Keys tab and click Create key. Keys look like alm_live_… or alm_test_…. Keep them out of public bundles and source control. Mint keys from the dashboard with step-up — API keys cannot be created through MCP.

Hosted HTTP MCP tools enforce MCP-layer read and write scopes on each tool call. Dashboard key minting today issues org API scopes such as models:read by default — not the MCP read/write pair. For full automation with a dashboard-minted key, prefer the stdio path below (alumia mcp --stdio uses the same REST credentials without MCP scope gating).

MCP write tools cannot perform browser-only dashboard mutations (workspace changes, project sharing, org settings, memory deletes). Use the app for those operations.

2. Hosted (HTTP)

Pass the key as Authorization: Bearer alm_live_…. Example client config (most desktop clients accept this shape):

{
  "mcpServers": {
    "alumia": {
      "url": "https://app.alumia.com/mcp",
      "headers": {
        "Authorization": "Bearer alm_live_xxx"
      }
    }
  }
}

3. Local (stdio) — recommended for automation

For clients that only speak stdio, use ALUMIA_BASE_URL (not ALUMIA_API_URL):

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "alumia": {
      "command": "bunx",
      "args": ["-y", "@hasna/alumia", "mcp", "--stdio"],
      "env": {
        "ALUMIA_API_KEY": "alm_live_xxx",
        "ALUMIA_BASE_URL": "https://alumia.com"
      }
    }
  }
}

Or install into local agent clients with alumia mcp install --target claude|codex|gemini.

Codex CLI

~/.codex/config.toml

[mcp_servers.alumia]
command = "bunx"
args = ["-y", "@hasna/alumia", "mcp", "--stdio"]
env = { ALUMIA_API_KEY = "alm_live_xxx", ALUMIA_BASE_URL = "https://alumia.com" }

Gemini CLI

~/.gemini/extensions/alumia/gemini-extension.json

{
  "name": "alumia",
  "version": "1.0.0",
  "mcpServers": {
    "alumia": {
      "command": "bunx",
      "args": ["-y", "@hasna/alumia", "mcp", "--stdio"],
      "env": {
        "ALUMIA_API_KEY": "alm_live_xxx",
        "ALUMIA_BASE_URL": "https://alumia.com"
      }
    }
  }
}

4. Tools (hosted HTTP)

Tool	MCP scope
`alumia_get_balance`	read
`alumia_list_agents`	read
`alumia_list_projects`	read
`alumia_list_sessions`	read
`alumia_list_files`	read
`alumia_search_memories`	read
`alumia_list_connectors`	read
`alumia_get_connector_catalog`	read
`alumia_create_memory`	write
`alumia_create_session`	write

Mutating tools fail closed if the key lacks the MCP write scope. Every invocation is audit-logged (mcp.tool.invoked or mcp.tool.invoked.mutating) so operators can replay the trail.

Resources and prompts

Name	Kind	Purpose
`alumia_org_snapshot`	resource (`alumia://org`)	Counts of agents, projects, and sessions in the calling org.
`alumia_summarize_org`	prompt	Starter prompt for summarizing org activity.

5. Discovery

The server descriptor is published at /.well-known/mcp.json. Tooling that follows the MCP discovery spec can auto-configure from that.

Search docs