TPF MCP Bridge

tools/tpf-mcp now carries two product surfaces:

• local MCP bridge for Codex, Claude Code, OpenCode, VS Code Agent mode, Cursor, and similar local-agent tools
• optional hosted TPF backend on Cloudflare Workers for session persistence, scaffold generation, and artifact delivery

The local bridge is the canonical end-user entrypoint. It reads OpenAI-compatible planner credentials from the local environment, runs the planner locally, and exposes the structured TPF tools over stdio.

The hosted backend is now optional infrastructure. It no longer runs the planner. It only stores session state, generates scaffolds from validated configs, and serves artifacts when you opt into hosted mode.

Install and Use

Primary Codex install command:

codex mcp add tpf -- npx -y @pipelineframework/tpf-mcp-bridge

Manual Codex fallback in ~/.codex/config.toml:

[mcp_servers.tpf]
command = "npx"
args = ["-y", "@pipelineframework/tpf-mcp-bridge"]

Required local environment variables:

export TPF_LLM_ENDPOINT="https://api.openai.com/v1"
export TPF_LLM_MODEL="gpt-5"
export TPF_LLM_TOKEN="<your-openai-compatible-token>"

Optional bridge settings:

export TPF_MCP_API_BASE_URL="https://mcp.pipelineframework.org/api"
export TPF_MCP_API_TOKEN="<optional-tpf-backend-token>"

If TPF_MCP_API_BASE_URL is unset, the bridge runs fully locally:

• planner on your machine
• session state in-process
• scaffold ZIPs written to a local temp directory

If TPF_MCP_API_BASE_URL is set, the bridge still plans locally but uses the hosted backend for:

• session persistence
• scaffold generation
• signed artifact delivery

Supported clients:

• Codex: primary path via codex mcp add
• Claude Code: supported via claude mcp add or project .mcp.json
• OpenCode: supported via opencode.jsonc local MCP entry
• Cursor: supported via mcp.json stdio entry
• VS Code Agent mode: supported via .vscode/mcp.json
• ChatGPT Developer Mode: manual remote import later; not the primary path
• Ollama: supported as an OpenAI-compatible planner provider preset, not a separate MCP host

Important constraints:

• TPF becomes visible in a user’s local MCP list after install
• there is no current public searchable Codex marketplace listing for this bridge
• provider tokens should stay in the local environment, not in the browser UI
• private model endpoints such as localhost, 127.0.0.1, or LAN-local Ollama work because the bridge calls them locally

Host and Provider Presets

Host client and planner provider are separate concerns:

• Hosts: Codex, Claude Code, OpenCode, VS Code, Cursor
• Providers: OpenAI API, Ollama, or another OpenAI-compatible endpoint

Claude Code local install:

claude mcp add tpf --scope local \
  --env TPF_LLM_ENDPOINT=https://api.openai.com/v1 \
  --env TPF_LLM_MODEL=gpt-5 \
  --env TPF_LLM_TOKEN=<your-openai-compatible-token> \
  -- npx -y @pipelineframework/tpf-mcp-bridge

Claude Code project .mcp.json:

{
  "mcpServers": {
    "tpf": {
      "command": "npx",
      "args": ["-y", "@pipelineframework/tpf-mcp-bridge"],
      "env": {
        "TPF_LLM_ENDPOINT": "${TPF_LLM_ENDPOINT}",
        "TPF_LLM_MODEL": "${TPF_LLM_MODEL}",
        "TPF_LLM_TOKEN": "${TPF_LLM_TOKEN}"
      }
    }
  }
}

OpenCode opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "tpf": {
      "type": "local",
      "command": ["npx", "-y", "@pipelineframework/tpf-mcp-bridge"],
      "enabled": true,
      "environment": {
        "TPF_LLM_ENDPOINT": "https://api.openai.com/v1",
        "TPF_LLM_MODEL": "gpt-5",
        "TPF_LLM_TOKEN": "<your-openai-compatible-token>"
      }
    }
  }
}

VS Code .vscode/mcp.json:

{
  "servers": {
    "tpf": {
      "command": "npx",
      "args": ["-y", "@pipelineframework/tpf-mcp-bridge"],
      "env": {
        "TPF_LLM_ENDPOINT": "https://api.openai.com/v1",
        "TPF_LLM_MODEL": "gpt-5",
        "TPF_LLM_TOKEN": "<your-openai-compatible-token>"
      }
    }
  }
}

VS Code user-profile install example:

code --add-mcp "{\"name\":\"tpf\",\"command\":\"npx\",\"args\":[\"-y\",\"@pipelineframework/tpf-mcp-bridge\"]}"

Ollama provider preset:

export TPF_LLM_ENDPOINT="http://localhost:11434/v1"
export TPF_LLM_MODEL="gpt-oss:20b"
export TPF_LLM_TOKEN="ollama"

TPF_LLM_TOKEN=ollama is a compatibility placeholder for Ollama’s OpenAI-compatible API; the value is required by OpenAI SDK-compatible clients but ignored by Ollama.

Tools Exposed by the Local Bridge

• start_brief_session
• answer_contract_questions
• get_brief_session
• generate_scaffold

The local bridge intentionally does not expose the older compatibility tools. It pushes users toward the session-based workflow instead of a one-shot analyze/generate call.

Contract questions are proposal-first:

• the planner should infer a draft contract before asking
• users confirm, edit, or replace proposed fields instead of authoring every schema from scratch
• invalid planner output fails explicitly rather than silently falling back to heuristics
• persistence is modeled as an aspect/plugin concern, not as explicit save/persist business steps
• resume and re-entry belong to a separate query/resumption surface, not the main forward-processing pipeline
• forward pipeline steps must chain by adjacent output-to-input type unless a non-linear boundary is explicitly modeled

Advanced TPF concerns such as caching, replayability, idempotency, and checkpoint hand-offs are planner-visible, but they are treated as technical concerns, aspect recommendations, or focused follow-up questions rather than universal hard requirements.

For local-model testing in hosts such as OpenCode, prefer very explicit prompts:

Use only the TPF MCP tools. Do not call generic task, subtask, or delegation tools.
Call start_brief_session with this brief and return only status and sessionId.

Then continue with:

Use only the TPF MCP tools. Do not call generic task, subtask, or delegation tools.
Call get_brief_session for sessionId <SESSION_ID> and return only contractQuestions.

Use only the TPF MCP tools. Do not call generic task, subtask, or delegation tools.
Call answer_contract_questions for sessionId <SESSION_ID> with these answers and return only status and remaining contractQuestions.

Use only the TPF MCP tools. Do not call generic task, subtask, or delegation tools.
Call generate_scaffold for sessionId <SESSION_ID> and return only status and artifact.

If the host reports an invalid-arguments error for a generic task tool instead of one of the four TPF MCP tools above, the failure is usually in the host delegation layer rather than in the TPF bridge.

Hosted Backend

The Worker entrypoint remains src/worker.ts. It provides:

• /mcp for legacy remote access guidance
• /api/session
• /api/get-session
• /api/generate-scaffold
• /artifacts/... for signed ZIP downloads

The hosted backend stores:

• Durable Object session state
• KV snapshots and quotas
• R2 scaffold ZIP artifacts

It does not store raw provider tokens, and it no longer needs planner provider headers.

Local Development

Install and test:

npm --prefix tools/tpf-mcp install
npm --prefix tools/tpf-mcp test

Start the user-facing local bridge:

npm --prefix tools/tpf-mcp start

Start the older repo-local stdio server against local analysis/generation code:

npm --prefix tools/tpf-mcp run start:local

Start the Cloudflare Worker locally:

npm --prefix tools/tpf-mcp run start:worker