Naragate MCP Server

One portable tool layer so the same Naragate experience works on the custom web UI and on any MCP-capable agent surface — Claude Code, Claude Desktop, Cursor, Windsurf, Zed, VS Code, opencode, Codex, or your own harness.

                 ┌─ custom web UI (Angular)
Naragate backend ├─ MCP server  ──► any MCP harness (desktop / CLI / IDE)
(FastAPI+cache)  └─ Pi agent harness

The three layers (what a user actually needs)

Skills alone can't fetch data (they declare tools but don't ship them); agents+skills add orchestration but still have no data. The MCP bundle is the data layer — with it, skills run anywhere.

Credit safety (hard requirement)

This server never talks to Sectors directly. Every tool is a thin client over the Naragate backend, so evidence gathering, the Evidence Graph cache and credit accounting live in exactly one place. A warm re-run costs 0 additional Sectors calls, identical to the web UI. There is a test asserting the MCP package never references the Sectors API.

Install

uvx naragate-mcp           # run without installing (recommended)
pip install naragate-mcp   # or install into your environment
pipx install naragate-mcp

From a checkout: pip install -e mcp.

Point it at your backend (default http://127.0.0.1:5678):

export NARAGATE_BACKEND_URL="http://127.0.0.1:5678"
export NARAGATE_TOKEN="nrg_..."   # optional: act as your own account
naragate-mcp

Transport is stdio.

Acting as your own account (NARAGATE_TOKEN)

The backend owns the Sectors key and LLM configuration; this server never sees them. To use your own key, cache and credits, mint a token in the web UI (Settings → MCP & API Access) and set NARAGATE_TOKEN. Every request then carries Authorization: Bearer <token>, which the backend resolves to your email — the same identity the web session uses.

• Without a token the server falls back to the backend's deployment key (fine for single-user self-hosts; all callers share one key/ledger).
• whoami confirms the resolved account; get_setup_status reports missing config; bind_sectors_key sets your key off-web.
• Tokens are stored hashed server-side and revocable from the same settings page.

No backend? Start one in one command

This server depends on an engine, not on any particular hosted deployment. The engine runs standalone with no Redis (SQLite + in-process cache):

pip install naragate-engine && SECTORS_API_KEY=... naragate-engine
# or
docker run --rm -p 5678:5678 -e SECTORS_API_KEY=... ghcr.io/masdevid/naragate-engine

If no engine answers, tools fail with an actionable hint on how to start one. Set NARAGATE_BACKEND_URL to wherever the engine runs.

Tools

30 tools total — 15 high-level + 15 low-level (every primitive declared in skills/*/tools.yaml).

Low-level tools — full tools.yaml parity

Every primitive declared in skills/*/tools.yaml is also exposed, for harnesses that want to compose per-agent exactly like the Pi pipeline (check the cache, then fetch on a miss and merge back):

A test (tests/test_parity.py) asserts that every tool declared in any skills/*/tools.yaml exists on the server, so this can't drift.

Resources

• naragate://templates
• naragate://usage
• naragate://history
• naragate://claim/{claim_id}

Harness configuration

Claude Code

claude mcp add naragate \
  -e NARAGATE_BACKEND_URL=http://127.0.0.1:5678 \
  -e NARAGATE_TOKEN=nrg_... \
  -- uvx naragate-mcp

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "naragate": {
      "command": "uvx",
      "args": ["naragate-mcp"],
      "env": { "NARAGATE_BACKEND_URL": "http://127.0.0.1:5678", "NARAGATE_TOKEN": "nrg_..." }
    }
  }
}

opencode (opencode.json)

{
  "mcp": {
    "naragate": {
      "type": "local",
      "command": ["uvx", "naragate-mcp"],
      "enabled": true,
      "environment": { "NARAGATE_BACKEND_URL": "http://127.0.0.1:5678", "NARAGATE_TOKEN": "nrg_..." }
    }
  }
}

Cursor (.cursor/mcp.json) / Windsurf / Zed / VS Code

{
  "mcpServers": {
    "naragate": {
      "command": "uvx",
      "args": ["naragate-mcp"],
      "env": { "NARAGATE_BACKEND_URL": "http://127.0.0.1:5678", "NARAGATE_TOKEN": "nrg_..." }
    }
  }
}

Codex (~/.codex/config.toml)

[mcp_servers.naragate]
command = "uvx"
args = ["naragate-mcp"]
env = { NARAGATE_BACKEND_URL = "http://127.0.0.1:5678", NARAGATE_TOKEN = "nrg_..." }

Example prompts

• "Use naragate to verify: PE BBCA mahal di 25x."
• "List the naragate templates and run the nickel policy one."
• "Show my last 10 naragate analyses and the trend summary."
• "What's my Sectors credit usage?"

Tests

cd mcp
python -m pytest -q

Covers the REST client (mock transport), the tool surface, compact-report shaping, and the credit-safety guarantee. No live backend or Sectors access required.

Publishing

CI publishes via .github/workflows/publish-mcp.yml when a GitHub release is published (or gh workflow run publish-mcp.yml). It authenticates with PyPI Trusted Publishing (OIDC) — no API token secret. One-time setup on PyPI (project → Publishing → Add a new publisher):

→ https://pypi.org/manage/project/naragate-mcp/settings/publishing/

For local/manual publishing, publish.sh uses an API token instead:

mcp/publish.sh              # PyPI
mcp/publish.sh testpypi     # TestPyPI
mcp/publish.sh check        # dry run: build + twine check (no token, no upload)

publish.sh reads PYPI_TOKEN from the environment or the repo-root .env, builds with python -m build, validates with twine check, and uploads — the token is never echoed. Manual equivalent:

python -m build
python -m twine check dist/*
TWINE_USERNAME=__token__ TWINE_PASSWORD="$PYPI_TOKEN" python -m twine upload dist/*

Related

• Naragate README — project overview and the "Use Naragate from any MCP agent" section
• Skills — the 13 skills whose tools.yaml this server satisfies
• Agents — optional subagent topology for harnesses that support it
• Parity test — enforces that every skills/*/tools.yaml tool is exposed here