Pctx

pctx

The open source framework to connect AI agents to tools and mcp with Code Mode

—   T R U S T E D   B Y   —

    

Install

# Homebrew
brew install portofcontext/tap/pctx

# cURL
curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/portofcontext/pctx/main/install.sh | sh

# npm
npm i -g @portofcontext/pctx

Core Functionality

pctx can be run as a stateless HTTP server for Code Mode sessions or as a unified MCP server that exposes Code Mode functionality for registered upstream MCP servers.

# Start Code Mode for Python SDK
pctx start

# Start Code Mode as a unified MCP server
pctx mcp init
pctx mcp dev

Python SDK

Use the Python SDK if building agents in Python and want to run Code Mode with custom tools and/or MCP servers. The Python SDK is an HTTP client to the pctx server.

pip install pctx-client

from pctx_client import Pctx, tool
from agents import Agent # Use any Agent SDK
from agents.run import Runner # This example is OpenAI Agents SDK

@tool
def get_weather(city: str) -> str:
    """Get weather information for a given city."""
    return f"It's always sunny in {city}!"

pctx = Pctx(tools=[get_weather]) # or with mcp: servers=[your_mcp]

tools = pctx.openai_agents_tools() # Run Code Mode with any Agent SDK
agent = Agent(
    name="GreatCoder",
    model="litellm/openrouter/openai/gpt-oss-120b",
    instructions="You run code to complete complex tasks.",
    tools=tools,
)

Links

• Python SDK Quickstart and Docs
• Python API Reference

Node SDK

Coming soon

Unified MCP

Use the unified MCP to run Code Mode with MCP servers and want to persist the authentication connections and you do not need to use agent tools (non-mcp tools).

# Initialize config for upstream mcp connections
pctx mcp init

# Add HTTP or stdio MCP servers
pctx mcp add stripe https://mcp.stripe.com
pctx mcp add memory --command "npx -y @modelcontextprotocol/server-memory"

# Start as HTTP server (dev mode with UI)
pctx mcp dev

# Or start as stdio MCP server
pctx mcp start --stdio

For complete CLI documentation, see CLI.md. For configuration options, see Configuration Guide.

What is pctx?

pctx sits between AI agents and MCP servers. It aggregates multiple upstream MCP servers, handles authentication, and exposes tools through a unified Code Mode interface. Instead of agents managing connections to individual MCP servers, they connect once to pctx.

What is Code Mode?

Code mode replaces sequential tool calling with code execution. Rather than an agent calling tools one at a time and passing results through its context window, it writes code that executes in a sandbox. Read Anthropic's overview here.

Traditional MCP flow:

1. Agent calls getSheet(id)
2. Server returns 1000 rows → agent's context
3. Agent calls filterRows(criteria)
4. Server returns 50 rows → agent's context

With Code Mode:

const sheet = await gdrive.getSheet({ sheetId: "abc" });
const orders = sheet.filter((row) => row.status === "pending");
console.log(`Found ${orders.length} orders`);

Result: 98.7% reduction in tokens (150k → 2k) for this multi-step operation.

Features