@pinecall/mcp

Pinecall as an MCP server. Point a coding agent — Claude Code, Cursor, Codex, Antigravity, Windsurf, anything that speaks MCP — at this server and it can take you from zero to a production voice agent answering a real phone number without leaving the editor.

Not "an API wrapper with tools". The server ships a playbook: its MCP instructions teach the whole journey, and every tool carries its own manual, so a coding agent that has never seen Pinecall discovers the catalog, builds a sandboxed agent, talks to it, wires a phone number, and reads the live call log of the call you just made — on its own.

you: "build me a voice agent for my restaurant that takes reservations"

agent: whoami                    → org, plan, credits
       docs_search / get_doc     → reads the real docs before writing anything
       list_models · list_voices → picks STT/LLM/voice from the LIVE catalog
       play_voice                → 🔊 plays voice samples through your speakers
       configure_agent (dev-…)   → registers a sandboxed agent
       chat                      → talks to it until the prompt behaves
       list_phones               → finds a free number, wires it
       observe                   → 📞 you call; it watches the transcript live

Install

npx -y @pinecall/mcp install

One command, every IDE, and nothing else needs to be installed first — the server installs itself. It detects the assistants on the machine and writes the pinecall entry into each one's own config, in that host's own format: Claude Code, Codex (TOML), Antigravity, Cursor, Windsurf, Gemini CLI. Re-running repairs a drifted entry instead of duplicating it; --remove takes exactly the pinecall entry out and nothing else. Every write leaves a .bak next to the file.

npx -y @pinecall/mcp install --list      # what is detected, changes nothing
npx -y @pinecall/mcp install cursor      # only the ones you name
npx -y @pinecall/mcp install --remove    # uninstall

If you already have the Pinecall CLI, pinecall mcp install is the same thing with a friendlier spelling.

Or by hand, in any MCP client config:

{
  "mcpServers": {
    "pinecall": {
      "command": "npx",
      "args": ["-y", "@pinecall/mcp"]
    }
  }
}

The API key

Set PINECALL_API_KEY in your environment and you are done. But IDEs launch MCP servers without your shell — a macOS GUI app never sources ~/.zshrc — so the server discovers the key in order:

1. PINECALL_API_KEY in the process environment

2. ~/.pinecall/credentials (mode 0600, shared with the pinecall CLI)

3. a read-only scan of your shell rc files (~/.zshrc, ~/.bashrc, …) for the export — never executed, and on a hit the key is persisted to the credentials file so the fragile path runs exactly once

No key anywhere? The set_api_key tool stores one for the session (memory only; persist: true writes the credentials file). The key never appears in any tool result, log line, or error — the server scrubs it from everything it emits.

Related MCP server: agentline-mcp

The tools

Eighteen, in journey order. Each ships a manual that is assembled into the server's instructions — a tool cannot exist here without documenting itself.

What is deliberately absent

• No spec-runner. Testing is conversational: chat with the agent, read the transcript, fix the prompt. A transcript you read is the check.

• No outbound dialling, no account creation. Real phones cost money and ring real people; accounts come from pinecall.io.

• No production configuration. configure_agent refuses any slug that does not start with dev- — no flag, no override. Registering an agent hot-reloads the live one, so touching a production slug would clobber the agent a running process owns, and its next reconnect would clobber you back. Production agents are deployed from code, never from an editor session.

The safety model, in one paragraph

dev- is the whole convention: anything the MCP creates is a sandbox, and the one mutating tool that could reach production refuses to. chat works against production because it only talks. subscribe hands the human a Stripe URL rather than touching billing itself — and warns that switching plans on an existing subscription is an immediate, prorated, real charge. Keys — yours and your providers' — transit once and are scrubbed from every output; the single sanctioned write is ~/.pinecall/credentials at 0600, and only when asked.

How honest the tools are

Things this server tells you that a thinner wrapper would not:

• configure_agent verifies phone routing after claiming a number and answers {routed: false, routedTo: "dev-other"} when another agent actually holds it — because the underlying protocol's refusal is fire-and-forget, and echoing the request back as the result would have you inviting calls to a number that reaches someone else.

• list_models joins the catalog with your org's BYOK keys: usable: false, unusableReason: "needs-byok" before you build a config that fails at call time.

• observe distinguishes silence from refusal: a quiet log returns {timedOut: true} forever without erroring; a bad token errors immediately with the reason.

• get_call never truncates silently: truncated: true plus the nextAfter cursor to continue from.

Development

The published package is a self-contained bundle — consumers need nothing but Node ≥ 20. Building it, however, reuses the Pinecall SDK's internals (its HTTP client, the chat WebSocket client, the call-log reducer), which the published @pinecall/sdk deliberately does not export. So development uses a sibling checkout:

git clone https://github.com/pinecall/sdk
git clone https://github.com/pinecall/mcp
cd sdk && npm install && npm run build     # dist/cli.js — run_agent drives it
cd ../mcp && npm install                    # links pinecall-sdk → ../sdk
npm run build                               # tsup bundles sdk internals in
npm test                                    # 215 tests; live ones need PINECALL_API_KEY

The pinecall-sdk/src/** imports resolve through an esbuild/vitest alias because the sdk's exports map — correct for its consumers — would block them. Releases are tag-driven (v* → GitHub Actions → npm Trusted Publishing with provenance); CI reproduces the sibling layout.

License

MIT