ingestion-mcp

A small, read-only Model Context Protocol server that lets an AI host (e.g. Claude Code) answer questions about your Kenda token spend and waste straight from the terminal — "how much did I spend this week?", "which agent is wasting the most?".

It is a query surface only: it never captures or writes usage. It reads the token-authed /collector/* endpoints of the Kenda API using the endpoint + token from ~/.kenda/config.json (the same ingest token the Kenda collector writes), which resolve the token to its org server-side — so the terminal needs no browser/Auth0 session.

Tools

Install

uv tool install ingestion-mcp     # or: pipx install ingestion-mcp

The console script kenda-mcp runs the stdio server. uvx ingestion-mcp runs it without installing anything.

uv and pipx are recommended over a bare pip install because this ships a command-line entry point, and pip refuses to install into a Homebrew or distro-managed interpreter at all (error: externally-managed-environment, PEP 668). If you only have pip, use pip install --user ingestion-mcp. Both uv and pipx install into ~/.local/bin, which is not on PATH by default on macOS — if kenda-mcp is not found afterwards, that is why.

Configure

The server reads ~/.kenda/config.json:

{
  "endpoint": "https://api.kenda.app",
  "token": "kenda_your-ingest-token"
}

Only endpoint and token are required for queries. Both are written for you by kenda-collect init (the Kenda collector) or the Claude Code plugin's /kenda-setup. Environment variables override the file (KENDA_ENDPOINT, KENDA_TOKEN) for CI and power users.

Use with your AI host

The server is plain stdio MCP: every host below runs the same one-line command, kenda-mcp — only the config file differs. After registering, ask your assistant: "what did I spend this week?" or "which agent is wasting the most?".

Claude Code

.mcp.json in the project (or claude mcp add kenda -- kenda-mcp):

{
  "mcpServers": {
    "kenda": { "command": "kenda-mcp" }
  }
}

Cursor

~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "kenda": { "command": "kenda-mcp" }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json (docs):

{
  "mcpServers": {
    "kenda": { "command": "kenda-mcp" }
  }
}

VS Code (Copilot agent mode)

.vscode/mcp.json for one workspace — or run MCP: Open User Configuration from the command palette to register it for all workspaces. Note the key is servers here, not mcpServers:

{
  "servers": {
    "kenda": { "type": "stdio", "command": "kenda-mcp" }
  }
}

Codex CLI

~/.codex/config.toml (or codex mcp add kenda -- kenda-mcp):

[mcp_servers.kenda]
command = "kenda-mcp"

Gemini CLI

~/.gemini/settings.json (or .gemini/settings.json in a project):

{
  "mcpServers": {
    "kenda": { "command": "kenda-mcp" }
  }
}

Troubleshooting

If your host reports the server as failed, run the built-in self-test — it works even when the mcp package is broken, and tells you whether the problem is your config, the network, or the host:

kenda-mcp --check

It prints the version, the config it resolved (token masked), and the result of one live API call; exit code 0 means the server side is healthy, so the problem is host config.

Develop

python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
ruff check .
pytest

The HTTP query layer is pure stdlib and unit-tested (tests/test_query.py); the MCP transport is driven end-to-end with an in-memory client (tests/test_server.py), including a schema-regression test that pins host-safe tool shapes; the --check doctor mode is covered by tests/test_check.py. The mcp package is a runtime dependency, so all suites run in CI.

License

MIT — see LICENSE.