# Connect agents through the CLI

> Give Claude Code, Codex, Cursor or an agent on local models Oatmilk's tools with oatmilk mcp.

Source: https://app.getoatmilk.com/docs/terminal/agents

Oatmilk's [MCP server](https://app.getoatmilk.com/docs/mcp.md) runs inside Oatmilk at `/api/mcp`, and most AI apps connect to it directly. Some agents can only start a local command. For those, `oatmilk mcp` is a small MCP server on standard input and output that forwards every request to your Oatmilk, signed in as the CLI.

Use it when:

- the agent only supports command (stdio) servers;
- you want the agent to use the sign-in you already made with `oatmilk login`, or an API key from the environment, instead of its own;
- the agent runs on a machine that can reach your Oatmilk but can't open a browser to sign in.

## 1. Sign in once

```bash
oatmilk login                                         # the hosted Oatmilk
oatmilk login --host https://books.example.com       # or your own
```

For an agent that runs unattended, set `OATMILK_API_KEY` in its environment instead, with only the permissions it needs. A read-only key can't change the books, whatever the agent tries.

## 2. Print the setup for your apps

```bash
oatmilk mcp config
oatmilk mcp config --host https://books.example.com
```

It prints ready-to-paste setup for Claude Code, Codex, Gemini CLI and Cursor, both for connecting to the server directly and through the CLI.

## 3. Add it to your agent

**Claude Code:**

```bash
claude mcp add oatmilk -- npx -y @getoatmilk/cli mcp
claude mcp add oatmilk -- npx -y @getoatmilk/cli mcp --host https://books.example.com   # your own Oatmilk
```

**Any app with an `mcp.json`** (Cursor, Windsurf, Claude Desktop and others):

```json title="mcp.json"
{
  "mcpServers": {
    "oatmilk": {
      "command": "npx",
      "args": ["-y", "@getoatmilk/cli", "mcp", "--host", "https://books.example.com"]
    }
  }
}
```

Leave out `"--host"` and the address for the hosted Oatmilk. If you installed the CLI, `"command": "oatmilk", "args": ["mcp"]` starts faster.

## Choose which tools it sees

Agents work better with fewer tools. `--toolset` limits the bridge to one or more of Oatmilk's [toolsets](https://app.getoatmilk.com/docs/mcp.md#choose-what-the-assistant-sees), separated by commas:

```bash
claude mcp add oatmilk-receipts -- npx -y @getoatmilk/cli mcp --toolset inbox,transactions
```

## Agents on local models

The bridge forwards to any Oatmilk, so an agent running on Ollama or LM Studio can use a [self-hosted Oatmilk](https://app.getoatmilk.com/docs/self-hosting.md) without anything leaving your network. Small models call tools less reliably, so use a tool-calling model of 9B parameters or more, and an API key with narrow permissions.

[opencode](https://opencode.ai) with Ollama and the bridge, in `opencode.json`:

```json title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": { "baseURL": "http://localhost:11434/v1" },
      "models": { "qwen3.5:9b": { "name": "Qwen 3.5 9B" } }
    }
  },
  "mcp": {
    "oatmilk": {
      "type": "local",
      "command": ["npx", "-y", "@getoatmilk/cli", "mcp", "--host", "https://oatmilk.localhost"],
      "environment": { "NODE_EXTRA_CA_CERTS": "/path/to/oatmilk/self-host/oatmilk-local-ca.crt" },
      "enabled": true
    }
  }
}
```

`NODE_EXTRA_CA_CERTS` is only needed for a `*.localhost` installation; see [Sign in and choose a company](https://app.getoatmilk.com/docs/terminal/sign-in.md#your-own-oatmilk).

## Check it

Ask the agent "Which Oatmilk company am I in?" It should answer with your company's name. If it can't reach Oatmilk:

- Run `oatmilk whoami --host …` with the same address. Exit code `3` means the CLI isn't signed in there.
- Add `--debug` to the bridge's arguments to print each request to standard error, which most agents keep in their MCP log.
- An agent that starts the bridge from a different user or folder may not see your sign-in. Give it `OATMILK_API_KEY`, or the same `OATMILK_CONFIG_DIR`.