POMA AI MCP Servers

POMA AI ships two separate Model Context Protocol (MCP) servers, one per product. Pick the one that matches what you're doing — they cover disjoint tool surfaces, not overlapping ones. Both work with any MCP-aware client (Claude Code, Claude Desktop, Cursor, your own agent).

Server	Tools it exposes	What it gives you
poma-mcp	primecut_ingest, primecut_status, primecut_get_result, primecut_resume	PrimeCut document ingestion — returns parsed chunks + chunksets (and optionally the raw .poma archive).
poma-grill-mcp	grill_ingest, grill_ingest_sync, grill_ingest_resume, grill_ingest_batch, grill_jobs_status, grill_search, grill_explain	Grill context engine — server-side index + hybrid search returning prompt-ready context. Available as a hosted endpoint or local binary; Go and Node implementations both ship.

Authentication: both servers read POMA_API_KEY from the env, accept -token as a CLI flag, accept a per-call token arg, or (HTTP only) read x-api-key / Authorization: Bearer. The kind of key differs by server:

Server	Key kind	Prefix
poma-mcp	Account-level	poma_acc_…
poma-grill-mcp	Grill project-level	poma_prod_gr_… (Create a Grill project)

Which one should I use?

What do you need to do?

   ┌── Ingest a doc and get chunk JSON, chunksets, or the .poma archive
   │       └──▶ poma-mcp
   │
   ├── Ingest a doc into a Grill namespace and search it for RAG context
   │       └──▶ poma-grill-mcp
   │
   └── Both
           └──▶ Install BOTH servers side-by-side (different commands, different keys)

There is no "all-in-one" server today. If you want both products, install both binaries (or install poma-mcp and point at the hosted Grill endpoint for the Grill side).

Looking for the hosted Grill endpoint? https://mcp.poma-ai.com/grill/v1. No local install required — see poma-grill-mcp's Option B (hosted).

Common setup

Every MCP client uses the same shape — command + args + env for stdio servers, or url + headers for hosted HTTP servers. Pick the snippet that matches your client and continue on the per-server page.

Claude Code · ~/.claude/claude.json

{
  "mcpServers": {
    "poma": {
      "command": "/full/path/to/poma-mcp",
      "args": ["-input", "-"],
      "env": { "POMA_API_KEY": "your-api-key" }
    }
  }
}

Claude Desktop · claude_desktop_config.json

{
  "mcpServers": {
    "poma": {
      "command": "/full/path/to/poma-mcp",
      "args": ["-input", "-"],
      "env": { "POMA_API_KEY": "your-api-key" }
    }
  }
}

Cursor · ~/.cursor/mcp.json

{
  "mcpServers": {
    "poma": {
      "command": "/full/path/to/poma-mcp",
      "args": ["-input", "-"],
      "env": { "POMA_API_KEY": "your-api-key" }
    }
  }
}

After saving, restart the client (Claude Desktop especially needs a full restart). Confirm the server is running by asking the agent to list its tools — you should see primecut_* (from poma-mcp) or grill_* (from poma-grill-mcp) depending on which one you wired in.

Authentication

Both servers accept the same credential sources (only the kind of key differs — see the table at the top of this page):

Source	Precedence	When to use
POMA_API_KEY env var	lowest	Local development; one shared key per agent process.
-token <key> CLI flag	middle	Long-running services where the env is fixed by platform.
token in tool args	highest	Per-call override (e.g. multi-tenant proxy).
x-api-key / Authorization: Bearer header	HTTP only	Hosted Grill MCP at https://mcp.poma-ai.com/grill/v1, or your own HTTP-mode deployment.

For poma-grill-mcp, the key must be a Grill project API key (prefix poma_prod_gr_…) — account-level keys are rejected at the /grill/* boundary. See Grill authentication.

Pages

• poma-mcp — PrimeCut document-ingestion server (primecut_* tools).
• poma-grill-mcp — Grill context-engine server (grill_* tools), Go + Node implementations, hosted HTTP option.

See also

• Grill overview — the API the MCP tools speak.
• PrimeCut SDK — same ingestion flow, programmatic.
• POMA CLI — same workflow from the shell.