npm package: @pantheon.ai/mcp
Description: Pantheon MCP
Latest version: 0.2.1

Pantheon MCP

Overview
- MCP server for Pantheon API access (projects, branches, explorations).
- Transports: stdio and Streamable HTTP.
- API base URL: `https://pantheon-ai.tidb.ai/`.

Pantheon (concepts inferred from source code in /Users/gaolinjie/PycharmProjects/baas)
- Project (Forest): A project maps to a Pantheon "forest". All tool `project` or `projectId`
  parameters identify a forest ID.
- Snap: A snapshot of a container execution in a forest. Snaps form a lineage via `SourceSnapID`
  (parent), and include filesystem state, command, envs, labels, and status.
- Branch: A branch is a workspace lineage of snaps in Pantheon. Branch tools operate on a branch
  identifier that represents a line of execution (a sequence of related snaps).
- Exploration: A higher-level grouping of snaps created by running a prompt sequence from a
  source snap (branch root) and then appending an analysis step. Explorations label each snap with
  an `exploration` name and `snap_type` so they can be grouped and previewed.
- Snap types (labels):
  - `root`: project initialization snap (starting point).
  - `execution`: a normal prompt execution step.
  - `artifacts`: the final analysis step that summarizes work and quality.
- Relationship summary:
  - A project (forest) contains many snaps.
  - A branch is a lineage through snaps (parent/child via `SourceSnapID`).
  - An exploration is a named set of snaps along a branch, ending in an artifacts snap.

Authentication
- Stdio: `npx @pantheon.ai/mcp stdio <Api-Key>` (API key required).
- HTTP: `PORT=9986 npx @pantheon.ai/mcp http [Optional Api-Key]`.
  - If no API key is provided, clients must send an `Authorization` header.
  - The server injects `Authorization: Bearer <Api-Key>` when a key is provided.

HTTP Server
- Default port: `9986` (override with `PORT`).
- Endpoint: `POST /mcp`.
- Allowed hosts: `pantheon-ai.tidb.ai`, `localhost`.

Tool Conventions
- Inputs are split into `params` and `body`.
- On success, tools return `content` (text) and most return `structuredContent`.
- On errors, tools return `content` with an error message string.
 - Branch tools operate on branches; exploration tools create and group snaps via labels.

Tools

listProjects
- Description: List Pantheon projects.
- Params:
  - `page` (int, min 1)
  - `size` (int, min 1, max 100)
- Body: none
- Output: paged `project`

createProject
- Description: Create a Pantheon project.
- Params: none
- Body:
  - `first_prompt` (string, required)
  - `project_type` (`general` | `github`, required)
  - `github_repo_id` (number, optional)
  - `github_installation_id` (number, optional)
  - `env_id` (string, optional)
- Output: `project`

listProjectBranches
- Description: List branches for a project.
- Params:
  - `projectId` (string, required)
  - `page` (int, min 1)
  - `size` (int, min 1, max 100)
- Body: none
- Output: paged `branch`

createProjectBranch
- Description: Create a new branch under a project.
- Params:
  - `projectId` (string, required)
- Body:
  - `name` (string, required)
  - `display_name` (string, required)
  - `parent_id` (string, required)
  - `project_id` (string, required)
- Output: `branch`

getProject
- Description: Get a project by id.
- Params:
  - `projectId` (string, required)
- Body: none
- Output: `project`

getProjectBranch
- Description: Get branch metadata.
- Params:
  - `projectId` (string, required)
  - `branchId` (string, required)
- Body: none
- Output: `branch`

listProjectChildrenBranches
- Description: List child branches of a branch.
- Params:
  - `projectId` (string, required)
  - `branchId` (string, required)
- Body: none
- Output: `branch[]`

executeProjectBranchLLM
- Description: Execute an LLM run on a branch.
- Params:
  - `projectId` (string, required)
  - `branchId` (string, required)
- Body:
  - `prompt` (string, required)
  - `agent` (string, optional)
  - `tool_use_id` (string, optional; leave blank if unknown)
  - `baseline_branch_id` (string, optional)
- Output: branch execution result

getProjectBranchOutput
- Description: Fetch a branch execution output.
- Params:
  - `projectId` (string, required)
  - `branchId` (string, required)
  - `fullOutput` (boolean, optional, default false)
- Body: none
- Output: API response (untyped)

createProjectExploration
- Description: Create an exploration (fan-out) from a parent branch.
- Params:
  - `projectId` (string, required)
- Body:
  - `parent_branch_id` (string, required)
  - `shared_prompt_sequence` (string[], min 1, max 4)
  - `num_branches` (int, min 1, max 50, optional, default 3)
  - `agent` (string, optional)
- Output: exploration

listProjectExplorations
- Description: List explorations for a project.
- Params:
  - `projectId` (string, required)
- Body: none
- Output: exploration[]

getProjectExplorationResult
- Description: Get exploration result details.
- Params:
  - `projectId` (string, required)
  - `explorationId` (string, required)
- Body: none
- Output: exploration result

readProjectBranchFS
- Description: Read a file or directory from a branch file system.
- Params:
  - `projectId` (string, required)
  - `branchId` (string, required)
  - `path*` (string, required; root path `/` is branch workdir)
- Body: none
- Output:
  - Directory: text table of entries with name/size/mode/modified.
  - File: text payload with file metadata and content.

Pantheon MCP Tools (baas: pantheon-infra/pantheon-mcp-server)
The Pantheon MCP server in /Users/gaolinjie/PycharmProjects/baas exposes a different set of tools.
Descriptions below are based on its Go implementation and reflect actual runtime behavior.

parallel_explore
- Description: Run the same prompt sequence in multiple parallel explorations from a source snap.
  Each exploration adds an automatic final analysis step (artifacts). If `max_results` is greater
  than `parallels_num`, an asynchronous auto-exploration pass is scheduled to generate more results.
- Params:
  - `source_snap` (string, required)
    - If an artifacts snap is provided, it is redirected to its parent execution snap.
  - `project` (string, required)
    - Project/forest ID that contains `source_snap`.
  - `shared_prompt_sequence` (string or string[], required)
    - 1 to 4 prompts. A final analysis prompt is always appended automatically.
  - `parallels_num` (int, optional, default 3; range 1-50)
  - `max_results` (int, optional; range 1-50)
    - Default is 1 in code, but it is automatically raised to at least `parallels_num`.
- Output:
  - Text summary of explorations, per-step results, and execution metadata.
- Notes:
  - Exploration names are auto-generated with unique suffixes.
  - In HTTP mode, this tool supports streaming progress notifications.

project_init_exploration
- Description: Initialize a project by creating (or reusing) a root snap.
- Params:
  - `project` (string, required)
- Behavior:
  - Ensures seed snap `claude-sandbox-3-2-1` exists (Docker image `ianzhai/claude-sandbox:3.2`).
  - Creates root snap named `root` if missing.
  - Labels root with `project`, `exploration=root`, `snap_type=root`.
- Output:
  - JSON containing `status`, `project`, `start_snap_id`, `message`, and `next_steps`.

preview_exploration
- Description: Summarize a single exploration and return the latest snap ID and output.
- Params:
  - `exploration_name` (string, required)
  - `project` (string, required)
  - `show_progress` (boolean, optional, default false)
- Behavior:
  - Groups snaps by labels and envs; detects status from snap state and artifacts analysis.
  - If exploring or running, waits briefly before returning.
- Output:
  - When `show_progress=false`: latest snap info + unified metadata.
  - When `show_progress=true`: full per-step progress list.

list_projects
- Description: List all non-system projects (forests).
- Params: none
- Behavior:
  - Filters out forests starting with `__`.
- Output:
  - `projects` list with metadata.

list_explorations
- Description: List explorations within a project.
- Params:
  - `project` (string, required)
- Behavior:
  - Groups snaps by exploration label.
  - Filters internal explorations named `unlabeled` and `root`.
  - Computes latest snap, snap output, and status metadata.
- Output:
  - `explorations` map keyed by exploration name plus a formatted tree view.

read_snap_file
- Description: Read a file or list a directory from a snap filesystem.
- Params:
  - `snap_id` (string, required)
  - `project` (string, required)
  - `path` (string, optional, default "")
    - Empty string lists home directory.
    - `/home/claude/...` is normalized to the snap mount root.
- Output:
  - Directory: JSON with `success` and `data` list of file metadata.
  - File: raw file content string.

kv_set
- Description: Store a key/value pair with TTL.
- Params:
  - `key` (string, required)
  - `value` (string, required)
  - `ttl_seconds` (int, optional, default 3600, min 1)
- Output:
  - Text confirmation on success.

kv_get
- Description: Retrieve a value by key.
- Params:
  - `key` (string, required)
- Output:
  - JSON with `key` and `value` when found.
  - Error tool result when missing or expired.