# MCP — the agent API

> Point Claude Desktop, Cursor, or any MCP client at mcp.primdb.com with a project token to deploy, query data, and read feedback.

PrimDB exposes an agent-readable API over the Model Context Protocol (MCP). Point Claude Desktop, Cursor, or any MCP/agent client at it with a single project-scoped token and it can deploy, promote, query your database, manage Redis / storage / env, and read feedback notes — all scoped to one project.

## 1. Create a token

In the dashboard: your project → **Settings → API tokens → New token**. Copy the value shown once (format `primdb_mcp_<project>_<random>`). It is project-scoped: a token can only ever touch its own project. Revoke it any time from the same screen.

## 2. Connect

- **Endpoint:** `https://mcp.primdb.com`
- **Auth:** `Authorization: Bearer primdb_mcp_...`
- **Transport:** HTTP (JSON-RPC 2.0)
- **Rate limit:** 1000 requests/min per token (`429` + `Retry-After` when exceeded)

### Claude Desktop / Cursor (mcp.json)

```json
{
  "mcpServers": {
    "primdb": {
      "url": "https://mcp.primdb.com",
      "headers": {
        "Authorization": "Bearer primdb_mcp_..."
      }
    }
  }
}
```

### Direct HTTP (any agent)

```bash
curl -s https://mcp.primdb.com \
  -H "Authorization: Bearer primdb_mcp_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## 3. Tools

| Category | Tools |
| --- | --- |
| Project | `get_project` |
| Deploy | `list_deployments`, `get_deployment_status`, `promote`, `rollback` |
| Postgres | `query_sql`, `list_tables` |
| Redis | `redis_get`, `redis_set`, `redis_del`, `redis_keys` |
| Storage | `storage_list`, `storage_get_url`, `storage_put_text`, `storage_delete` |
| Env | `list_env`, `set_env`, `delete_env` |
| Notes | `get_notes`, `list_note_routes`, `create_note`, `resolve_note` |

> **Honest note.** Data tools resolve the project’s relevant service automatically; pass `serviceId` only if a project has more than one of a kind. `get_logs` / `stream_logs` from the spec are not yet available (no container-log pipeline today).

## Agent quickstart — prompts to paste

Once your MCP client is connected, tell your agent what you want in plain language. Some starters:

- “Deploy this repo to PrimDB and give me the preview URL.”
- “List my recent deployments and promote the latest passing preview to production.”
- “Run this SQL query against my PrimDB Postgres and summarize the rows.”
- “Set the `STRIPE_KEY` env var on my PrimDB project, then redeploy.”
- “Show the open preview feedback notes and resolve the one about the checkout button.”

## Security

- A token is bound to **one project** — it can never reach another project’s deployments, data, env, or notes.
- Postgres / Redis / Storage access goes through the same per-tenant isolation the rest of the platform uses (DB roles, Redis ACLs, bucket scoping).
- Every tool call is audit-logged (`mcp_<tool>` plus the token id). Revoke instantly.
- Secrets (`set_env` values, connection strings) are never written to audit logs.

---

Source: https://primdb.com/docs/mcp