Connect agents through the CLI

Oatmilk's MCP server 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

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

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:

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):

{
  "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, separated by commas:

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 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 with Ollama and the bridge, in 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.

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.