Source: http://www.poma-ai.com/docs/mcp/

# 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`**](/mcp/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`**](/mcp/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](/grill/getting-started/projects)) |

## Which one should I use?

```text
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` — OAuth 2.0 via your Console login, no local install and no key in your config. See `poma-grill-mcp`'s [Option B (hosted)](/mcp/grill-mcp#option-b-hosted-http-endpoint-no-install).

## 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.

::: code-group

```json [Claude Code · ~/.claude/claude.json]
{
  "mcpServers": {
    "poma": {
      "command": "/full/path/to/poma-mcp",
      "args": ["-input", "-"],
      "env": { "POMA_API_KEY": "your-api-key" }
    }
  }
}
```

```json [Claude Desktop · claude_desktop_config.json]
{
  "mcpServers": {
    "poma": {
      "command": "/full/path/to/poma-mcp",
      "args": ["-input", "-"],
      "env": { "POMA_API_KEY": "your-api-key" }
    }
  }
}
```

```json [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). |
| OAuth 2.0 (browser login) | Hosted HTTP | Default for `https://mcp.poma-ai.com/grill` — the client handles the 401-challenge flow automatically. |
| `x-api-key` / `Authorization: Bearer` header | HTTP only | Static-key alternative for the hosted endpoint (CI, headless), 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](/grill/getting-started/authentication).

## Pages

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

## See also

- [Grill overview](/grill/) — the API the MCP tools speak.
- [PrimeCut SDK](/sdk/) — same ingestion flow, programmatic.
- [POMA CLI](/cli/) — same workflow from the shell.