# primitives mcp

> Serve one group over MCP stdio for Claude Desktop and other clients that launch a process.

Source: https://useprimitives.com/docs/cli/mcp

`primitives mcp` serves one group over MCP stdio, for clients that launch a local process instead of connecting to a URL, such as Claude Desktop.

```bash
primitives mcp --group agent-42
```

The process reads JSON-RPC on stdin and writes it on stdout, so you rarely run it by hand: your MCP client starts it. Logs go to stderr. If `primitives dev` is running you can also connect over HTTP instead; see [Connect a client](/docs/mcp/setup).

## Options

| Option | Description |
| --- | --- |
| `--group <GROUP>` | Required. The group whose primitives are exposed. It must exist: unlike `/mcp/<group>` over HTTP, stdio doesn't create it. Create it with [`primitives group create`](/docs/cli/group#create) |
| `--tools <PATTERNS>` | Comma-separated tool patterns to allow, such as `db_*,memory_*`. Defaults to every tool |
| `--data <DIR>` | Data directory. See [global options](/docs/cli#global-options) |

It takes no token and applies exactly the same permission checks as HTTP. A tool outside `--tools` isn't listed and can't be called. See the [tools reference](/docs/mcp/tools) for every tool name.

## Client configuration

Clients start the process in a directory of their choosing, so always pass an absolute `--data` path:

```json title="claude_desktop_config.json"
{
  "mcpServers": {
    "primitives": {
      "command": "primitives",
      "args": ["--data", "/Users/me/project/.primitives", "mcp", "--group", "agent-42", "--tools", "db_*,fs_*,memory_*"]
    }
  }
}
```

If the client can't find `primitives` on its `PATH`, use the full path to the binary, such as `/Users/me/.primitives/bin/primitives`.

To give memory recall real embeddings, set `PRIMITIVES_EMBEDDINGS_URL` and `PRIMITIVES_EMBEDDINGS_KEY` in the server's `env` block.

## Examples

Read-only access to databases and files:

```bash
primitives mcp --group agent-42 --tools 'db_query,fs_read,fs_search'
```

Everything except the vault:

```bash
primitives mcp --group agent-42 --tools 'db_*,fs_*,queue_*,memory_*,kv_*,storage_*,primitive_*'
```