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.