> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pramaan.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Give an AI agent every capability through the Model Context Protocol.

The Pramaan MCP server runs on your machine and talks to the API with your key. Add it to any
MCP client:

```json theme={null}
{
  "mcpServers": {
    "pramaan": {
      "command": "npx",
      "args": ["-y", "@pramaan/mcp"],
      "env": { "PRAMAAN_API_KEY": "sk_live_..." }
    }
  }
}
```

## Tools

| Tool | Does |
| - | - |
| `list_capabilities` | Without filters, namespace counts. With `namespace` or `query`, up to 50 rows and `nextCursor`. |
| `describe_capability` | Shows one capability's request and result schema and an example. |
| `run_capability` | Runs a capability; async ones return a job. |
| `get_job` | Reads a job's status and result. |
| `list_accounts` | Lists connected accounts. |
| `explain_route` | Shows the maximum cost and routed account before running. |
| `wait_job` | Waits up to 60 seconds, then returns the current job state. |
| `cancel_job` | Cancels a running job. |
| `get_balance` | Reads available and held credit. |
| `get_usage` | Reads daily usage, optionally by date range. |
| `list_outcomes` | Lists outcomes: a fixed sequence of capability steps under one business name. |
| `describe_outcome` | Describes an outcome's input and steps. |
| `estimate_outcome` | Shows an outcome plan and maximum cost without running. |
| `run_outcome` | Runs an approved plan; long runs return a job immediately. |

These tools keep the agent's context small. To give the agent one tool per capability for the
ids or small namespaces it uses most, add `--tools`:

```json theme={null}
"args": ["-y", "@pramaan/mcp", "--tools", "web.search,email.send"]
```

Named tools use safe names: `web.search` becomes `web_search`.

## Safety

* Tool results are untrusted data from third-party sources. Every tool description tells the
  agent to treat them as data, never as instructions.
* Capabilities with an external effect (sending, posting, paying) need an `idempotency_key`, so
  an agent that retries never repeats the action.
* Capabilities that reach a real person or cannot be undone need a person's yes. The server asks
  through your MCP client before each call and runs it only if they approve; clients without
  elicitation get `approval_required` instead. See [Approvals](https://docs.pramaan.dev/guides/approvals.md).

Named tools are capped at 50; narrow `--tools` patterns if startup refuses them.
For apps, register builder webhooks in the dashboard for `job.completed` and verify signatures.

The approval form shows the maximum cost and account before the yes. For member-scoped keys,
enter your own approving member ID in the form; the API checks your right to approve.
Read-only keys cannot run actions, even with approval. Inputs above 1,000,000 JSON bytes are refused.

Read the [capability skill](https://github.com/Pramaan-Dev/capabilities-lab/blob/main/docs/skills/pramaan-capabilities/SKILL.md)
for discovery, approval, jobs and error handling.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.