Allem MCP Server

Connect any MCP-capable AI assistant (Claude Code, Claude Desktop, …) to the Allem governance platform. Once connected, the assistant can register agents, run pre-flight authorization checks, log actions to the tamper-evident audit chain, read compliance intelligence, manage authorization scopes, and cryptographically verify the audit chain — which means it can write and test an Allem integration for you.

Transport: stdio (runs locally next to your dev environment).

60-second setup

1. Get the two required settings

• ALLEM_BASE_URL — where your Allem platform lives. There is no default on purpose — you must say which environment you mean:
  • local development: http://localhost:8000
  • production: your hosted Allem URL
• ALLEM_API_KEY — an org API key (alm_sk_test_... or alm_sk_live_...), created in the Allem console under Settings → API Keys.

2. Install it

pip install allem-mcp

That gives you an allem-mcp command. Every line below assumes it is on your PATH — which it is if you installed it into the environment your assistant runs in, or with pipx install allem-mcp.

backend/tests/test_get_started_snippets.py runs this install line in a clean virtualenv on every CI run, and starts the allem-mcp command it produces and speaks MCP to it. Until 2026-09-09 this README opened with a path into a repository checkout, because the package had never been published and there was nothing else to point at.

3a. Claude Code

claude mcp add allem \
  --env ALLEM_BASE_URL=http://localhost:8000 \
  --env ALLEM_API_KEY=alm_sk_test_YOUR_KEY \
  -- allem-mcp

3b. Claude Desktop

Add to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "allem": {
      "command": "allem-mcp",
      "env": {
        "ALLEM_BASE_URL": "http://localhost:8000",
        "ALLEM_API_KEY": "alm_sk_test_YOUR_KEY"
      }
    }
  }
}

4. Try it

Ask your assistant: "List my Allem agents and verify the audit chain."

Tools

Agents can be referenced by their friendly external_id (e.g. shuffle-triage-bot) everywhere — no need for database ids.

Deliberately not included

• Freeze lift / unfreeze — requires a console admin login (session auth), not an API key. Un-freezing an agent is a human decision made in the Allem console; no API key, and therefore no MCP tool, can do it. Don't hunt for it here.
• Anything else admin-session-gated (user management, API key management).

Development

cd sdk/allem-mcp
uv sync --extra dev
uv run --extra dev python -m pytest          # unit tests (mocked HTTP)
uv run python scripts/e2e_local.py           # end-to-end vs local platform
uv run python scripts/seed_evals.py          # seed data for evals.xml
npx @modelcontextprotocol/inspector uv run allem-mcp   # interactive inspector

Note: the dev venv is pinned to Python 3.11 (.python-version). Python 3.14 skips .pth files that carry the macOS hidden file flag, which breaks uv's editable installs — 3.11 matches the platform's locked stack and avoids this.

Follow-ups (out of scope for v1)

• Publishing to an MCP registry (with Asif).
• Website / llms.txt update to advertise the server.
• Remote streamable-HTTP transport, if demand appears.