@planoda/mcp-server

Connect Claude, Cursor, or any Model Context Protocol client to a Planoda workspace.

What this is: a small, dependency-free stdio bridge. It forwards JSON-RPC between your MCP client and Planoda's hosted MCP endpoint. It does not implement tools itself — the tool list, the schemas, and every permission check live on the Planoda server.

What Planoda is: an AI-native work platform (issues, projects, cycles, docs, agents). It's a hosted product at planoda.com and is pre-launch. This bridge is MIT-licensed and open source; the platform itself is not.

---

Requirements

• Node.js 20 or newer (uses the built-in fetch), or Docker
• A Planoda API key — Settings → API keys in your workspace

Install

You don't need to install anything globally. Every snippet below runs the package on demand via npx.

# Verify it works before wiring it into a client:
PLANODA_API_KEY=ttm_... npx -y @planoda/mcp-server --version

---

Client setup

Claude Code

claude mcp add planoda \
  --env PLANODA_API_KEY=ttm_your_key_here \
  -- npx -y @planoda/mcp-server

Planoda also serves MCP over HTTP directly, so you can skip this package entirely if you prefer:

claude mcp add --transport http planoda \
  https://planoda.com/api/mcp/streamable-http \
  --header "Authorization: Bearer ttm_your_key_here"

Use this package when your client only speaks stdio, or when you want the flag ergonomics (--profile, --workspace) without hand-editing a URL.

Claude Desktop

Edit claude_desktop_config.json:

• macOS — ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows — %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "planoda": {
      "command": "npx",
      "args": ["-y", "@planoda/mcp-server"],
      "env": {
        "PLANODA_API_KEY": "ttm_your_key_here"
      }
    }
  }
}

Restart Claude Desktop. Planoda appears in the tools menu.

Cursor

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project):

{
  "mcpServers": {
    "planoda": {
      "command": "npx",
      "args": ["-y", "@planoda/mcp-server"],
      "env": {
        "PLANODA_API_KEY": "ttm_your_key_here"
      }
    }
  }
}

Docker

docker build -t planoda/mcp-server .

{
  "mcpServers": {
    "planoda": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "PLANODA_API_KEY",
        "planoda/mcp-server"
      ],
      "env": {
        "PLANODA_API_KEY": "ttm_your_key_here"
      }
    }
  }
}

-i is required — MCP stdio needs stdin held open. Do not pass -t.

---

Configuration

Every option has a CLI flag and an environment variable. Flags win.

Flag	Env var	Default	Purpose
--api-key	PLANODA_API_KEY	—	Required. Prefer the env var.
--url	PLANODA_URL	https://planoda.com	Origin or full endpoint URL.
--profile	PLANODA_PROFILE	—	Narrow the tool surface (see below).
--ns	PLANODA_NAMESPACES	—	Narrow by namespace; wins over --profile.
--workspace	PLANODA_WORKSPACE	—	Target a workspace by slug.
--timeout	—	120000	Per-request timeout in ms.
--no-stream	PLANODA_STREAM=0	stream on	Disable the server→client SSE stream.
--verbose	PLANODA_VERBOSE=1	off	Mirror JSON-RPC traffic to stderr.

Tool profiles

Planoda exposes a large tool surface. Some clients have a tight budget for tool schemas, and a smaller surface also makes the model choose better. Pass --profile to scope it:

Profile	Covers
core	Issues, comments, search, notifications
issues	Issues, comments, labels, links, checklists
planning	Projects, cycles, initiatives, milestones, releases
support	Customer requests, customers, comments, issues
insights	Insights, dashboards, search (read-only)
deep-research	Just search + fetch, for ChatGPT-style connectors

"args": ["-y", "@planoda/mcp-server", "--profile", "core"]

Profiles only filter what's listed. They are a token-budget tool, not a security boundary — the actual boundary is your API key's scopes.

---

Security model

Read this before you decide how much to trust an agent with your workspace.

The bridge holds no authority. It has no tool definitions, no schemas, and no permission logic. It serializes JSON-RPC frames onto an HTTPS request and writes the response back to stdout. Forking or patching this package grants no additional access — everything is decided server-side from your API key.

Destructive tools require approval. Planoda's tool registry marks destructive operations (delete, bulkUpdate, bulkArchive, …) with a destructive flag. Every tools/call is evaluated against that flag before anything executes:

• Non-destructive tools run normally.
• Destructive tools run only if the session holds the destructive capability — which requires an appropriate workspace role and the acting user having opted in under Settings → Agents. Guest-role sessions never qualify.
• Otherwise the call is refused and you get a structured "approval required" result instead. The tool does not run. Re-issue it from an interactive Planoda agent session where a human can approve it.

Auto-approved destructive calls are recorded in the workspace audit log under the same agent.proposal.* trail as human-approved ones, so an MCP-driven change and an in-app one reconcile in one place.

The bridge passes an "approval required" result through untouched, exactly like any other tool result. This behavior cannot be disabled from the client side, and there is no flag in this package that bypasses it — by design.

Tenancy. An API key is bound to one workspace. Every read and write executes inside a row-level-security scope for that workspace and the acting user, so a session cannot observe or modify another workspace's data.

Handling your key. Prefer PLANODA_API_KEY over --api-key so the key stays out of shell history and process listings. The bridge sends it only to the configured Planoda origin, and never logs it — --verbose prints methods and ids, not headers. Revoke a key under Settings → API keys.

---

Troubleshooting

No API key — set PLANODA_API_KEY. In Claude Desktop and Cursor, it goes in the env block of the server entry, not your shell profile; those clients don't inherit your login shell.

Planoda rejected the credential (HTTP 401) — the key is wrong, revoked, or from a different workspace. Mint a fresh one under Settings → API keys.

Tools don't appear — restart the client fully after editing its config. Then run with --verbose and check stderr for the initialize exchange.

A tool returns "approval required" — working as intended; see the security model above. That is the guardrail, not an error.

npx is slow to start — pin the version (@planoda/mcp-server@0.1.0) or npm i -g @planoda/mcp-server and use planoda-mcp as the command directly.

---

Development

npm install
npm run build      # tsc → dist/
npm run typecheck

The bridge has zero runtime dependencies. TypeScript and @types/node are the only devDependencies.

Layout:

• src/index.ts — CLI entry, flag parsing, signal handling
• src/config.ts — config precedence and endpoint resolution
• src/bridge.ts — the stdio ⇄ Streamable HTTP proxy
• src/jsonrpc.ts — JSON-RPC framing and SSE parsing

License

MIT — see LICENSE.