Planoda Mcp Server

@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](./LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Planoda
• Source: Planoda/mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.