constellation MCP server

The constellation MCP (Model Context Protocol) server exposes the same operations as the pt CLI but as MCP tools — so MCP-native agent runtimes (Claude Desktop, Claude Code with .mcp.json, Cursor, Codex, ChatGPT custom connectors) can call them as part of a normal turn instead of as one-shot subprocesses.

Renamed (PLT-107)

The server identity was constellation-pt before the wiki tools were merged in. Update the server key in your config to constellation (examples below) — a one-time per-developer change. Setting the optional WIKI_BASE_URL env var additionally registers the 24 wiki tools (list_spaces, search_pages, get_page, traverse_dependencies, rebuild_space_index, …). The hosted Streamable-HTTP endpoint keeps its existing URL until a separate coordinated infra rename.

The wire protocol is stdio JSON-RPC for desktop / CLI agents and Streamable HTTP for ChatGPT. Backend: same REST API as the CLI.

The full source-of-truth setup notes live in tools/mcp-server/README.md. The summaries below are extracted for the most common setups.

Get an API key first

Both stdio and HTTP modes need a PT auth token. Generate one in the PT UI:

1. Log into PT at ${PT_BASE_URL}/settings/api-keys (production: https://constellation.planetb2b.com/projects/settings/api-keys).
2. Provide a label (e.g. "Claude Desktop MCP"), pick an expiry, click Generate.
3. Copy the token — it's shown once. The default lifetime is 90 days for non-admin users, 14 days for admin roles. Caps: 365 / 30 days respectively.

Tokens are revocable from the same page — revocation propagates within ~30 seconds across Directory, Project Tracker, and Catalog (30-second TTL on the principal-liveness cache).

Claude Code (.mcp.json)

Add to .mcp.json at the monorepo root (gitignored — the file is per-developer):

{
  "mcpServers": {
    "constellation": {
      "command": "npx",
      "args": ["tsx", "tools/mcp-server/src/index.ts"],
      "env": {
        "PT_BASE_URL": "https://constellation.planetb2b.com/projects",
        "WIKI_BASE_URL": "https://constellation.planetb2b.com/wiki",
        "PT_AUTH_TOKEN": "<paste API key JWT here>"
      }
    }
  }
}

For local dev against localhost:3002, swap PT_AUTH_TOKEN for a PT_AUTH_COOKIE that you grab from your browser dev tools:

{
  "env": {
    "PT_BASE_URL": "http://localhost:3002",
    "PT_AUTH_COOKIE": "constellation-auth=<paste value here>"
  }
}

Claude Code picks up the change next session.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your platform. Same shape as the Claude Code config above:

{
  "mcpServers": {
    "constellation": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/constellation/tools/mcp-server/src/index.ts"],
      "env": {
        "PT_BASE_URL": "https://constellation.planetb2b.com/projects",
        "WIKI_BASE_URL": "https://constellation.planetb2b.com/wiki",
        "PT_AUTH_TOKEN": "<token>"
      }
    }
  }
}

Note the absolute path — Claude Desktop runs from $HOME, not the repo root. Restart Claude Desktop after editing.

OpenAI Codex CLI

Codex CLI reads MCP servers from ~/.codex/config.toml (TOML, not JSON):

[mcp_servers.constellation]
command = "npx"
args = ["tsx", "/absolute/path/to/constellation/tools/mcp-server/src/index.ts"]
env = { PT_BASE_URL = "https://constellation.planetb2b.com/projects", WIKI_BASE_URL = "https://constellation.planetb2b.com/wiki", PT_AUTH_TOKEN = "<token>" }

Same auth options as Claude Code (swap to PT_AUTH_COOKIE for local dev). Restart any running Codex sessions after editing.

Smoke test. Ask Codex something like "use the constellation MCP to list my IN_PROGRESS tasks across all five projects" — it should call get_workspace_context and the per-project list_tasks tools without further prompting.

Cursor / Aider / other stdio MCP hosts

The same pattern applies — command + args + env, with whatever syntax that runtime's config uses (JSON for most, TOML for Codex). The repo-relative path works only for hosts that run from the repo root; otherwise use an absolute path. See tools/mcp-server/README.md for the canonical reference.

ChatGPT custom connector

The MCP server speaks Streamable HTTP in addition to stdio, so ChatGPT's Developer Mode custom connectors can talk to it directly — no local bridge required.

1. Mint a PT API key as above.
2. Add the connector: in ChatGPT, open Settings → Connectors → Advanced → Developer mode → Add custom MCP.
3. Fill in the URL (https://constellation-pt-mcp.vercel.app/api/mcp — the hosted MCP service is its own Vercel deployment, separate from PT_BASE_URL), authentication (Bearer token, paste the JWT), and a name.
4. Save and test in a new conversation.

Full ChatGPT setup walkthrough including the URL path and authentication mode is in tools/mcp-server/README.md.

What's exposed as MCP tools

The MCP server surfaces the same operations as the CLI subcommands, with MCP-style names (snake_case instead of kebab-case). The mapping is one-to-one, with one exception noted below (get_initiative_summary has two CLI spellings):

CLI subcommand	MCP tool name
pt workspace	get_workspace_context
pt find-project	find_project
pt list-projects	list_projects
pt get-project-overview	get_project_overview
pt create-project	create_project
pt update-project	update_project
pt delete-project	delete_project
pt initiative / pt get-initiative-summary	get_initiative_summary
pt list-initiatives	list_initiatives
pt create-initiative	create_initiative
pt update-initiative	update_initiative
pt delete-initiative	delete_initiative
pt list-tasks	list_tasks
pt list-epic-children	list_epic_children
pt get-task	get_task
pt create-task	create_task
pt update-task	update_task
pt list-issues	list_issues
pt get-issue	get_issue
pt create-issue	create_issue
pt update-issue	update_issue
pt assign-issue	(subsumed into update_issue)
pt escalate-issue	(subsumed into update_issue)
pt transition-issue	transition_issue
pt resolve-issue	resolve_issue
pt list-stages	list_stages

A few extras exist on the MCP side that don't have CLI equivalents (create_stage, reorder_stages).

When WIKI_BASE_URL is set, 24 additional wiki tools are registered (no CLI equivalent). They talk to the wiki module over its REST API only — the same Directory-issued token works across zones:

• Spaces — list_spaces, get_space, create_space, update_space, delete_space, decommission_space
• Pages — search_pages, get_page, list_child_pages, create_page, update_page
• Links & dependencies — list_page_links, link_pages, traverse_dependencies
• Attachments — get_attachment
• Maintenance — rebuild_space_index, append_space_log
• Lint (honesty loop) — lint_space, list_lint_findings, record_lint_finding, resolve_lint_finding
• Source ingestion — ingest_source, retract_source, revert_ingest_batch

See also

• CLI overview — when to use the CLI vs the MCP server.
• Subcommand reference — every operation, with arguments and examples.
• tools/mcp-server/README.md — canonical install + auth reference; this page is a summary.