agimus-mcp 0.4.0

MCP server for the Agimus data platform — connects AI coding tools to your ontology

Agimus MCP Server

Connects AI coding tools — Claude Desktop, Claude Code, Cursor, OpenAI Codex, and other Model Context Protocol clients — to the Agimus data platform. The server gives the AI live awareness of your ontology (entities, properties, links, types) and bundled reference docs for the Agimus Python SDK, so it writes correct code instead of guessing field names.

What the AI gets

Tools (13)

Discovery:

Tool	What it does
agimus_list_entities	Every entity, with PK, property/link counts
agimus_get_entity_schema	Full schema for one entity (properties + rich link details)
agimus_list_links	Every link in the ontology (both directions per link)
agimus_get_link	Full details for a link by api_name
agimus_list_datasets	All datasets, optionally filtered by source/name
agimus_get_dataset_schema	Columns, types, row count + SDK usage snippet
agimus_whoami	Tenant name, scope, rate limit for the current API key

Read (read-only — writes happen via the SDK in user code):

Tool	What it does
agimus_query_objects	Filter / sort / project / expand / paginate
agimus_get_object	Single object by primary key
agimus_get_related_objects	Traverse a link from one object (cursor-paginated)
agimus_count_objects	Cheap COUNT(*) with optional filter
agimus_distinct_values	Distinct values, optionally with frequency counts
agimus_aggregate	group_by + metrics (count/sum/avg/min/max/...)

Resources

• agimus://schema/entities/{entity} — live, full schema for one entity
• agimus://docs/sdk-reference — the full Agimus Python SDK reference (sourced directly from the SDK's README so it never drifts)

Install & configure

The recommended path is uvx — it auto-installs the latest version on first run and keeps it isolated. No prior pip install is required.

Claude Code

Add to ~/.claude/claude_code_config.json:

{
  "mcpServers": {
    "agimus": {
      "command": "uvx",
      "args": ["agimus-mcp"],
      "env": { "AGIMUS_API_KEY": "agm_your_api_key_here" }
    }
  }
}

Cursor

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "agimus": {
      "command": "uvx",
      "args": ["agimus-mcp"],
      "env": { "AGIMUS_API_KEY": "agm_your_api_key_here" }
    }
  }
}

OpenAI Codex

Add to ~/.codex/config.toml:

[mcp_servers.agimus]
command = "uvx"
args = ["agimus-mcp"]
env = { AGIMUS_API_KEY = "agm_your_api_key_here" }

Claude Desktop

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

{
  "mcpServers": {
    "agimus": {
      "command": "uvx",
      "args": ["agimus-mcp"],
      "env": { "AGIMUS_API_KEY": "agm_your_api_key_here" }
    }
  }
}

Alternative install: pip

If you prefer a pinned global install:

pip install agimus-mcp

Then replace "command": "uvx", "args": ["agimus-mcp"] with "command": "agimus-mcp" in any config above.

CLI options

agimus-mcp [--api-key agm_xxx] [--base-url URL] [--timeout SECONDS] [--log-level LEVEL]

Every flag has an environment-variable equivalent:

Flag	Env var	Default
--api-key	AGIMUS_API_KEY	(required)
--base-url	AGIMUS_BASE_URL	https://api.agimus.ai
--timeout	AGIMUS_TIMEOUT	30
--log-level	AGIMUS_LOG_LEVEL	WARNING

Logs are written to stderr — stdout is reserved for the MCP stdio protocol.

Programmatic use

from agimus_mcp import create_server

create_server(api_key="agm_...").run()

Security model

• The server authenticates with your Agimus API key — it can only see what the key allows.
• It runs locally as a subprocess of your AI tool. No hosted server, no open ports.
• All API calls go to https://api.agimus.ai (or your configured base URL) over HTTPS.

Development

This package lives in the Agimus monorepo at sdk/python-mcp/ alongside the agimus Python SDK that it wraps.

cd sdk/python-mcp
pip install -e ".[dev]"
pytest

The package depends on a published agimus SDK — for development against an unreleased SDK, install both in editable mode:

pip install -e ../python -e ".[dev]"

License

MIT