Skip to content
Back to search

pctx

pctx is the execution layer for agentic tool calls. It auto-converts agent tools and MCP servers into code that runs in secure sandboxes for token-efficient workflows.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/portofcontext/pctx with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/portofcontext/pctx'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/portofcontext--pctx/badge.svg)](/listings/portofcontext--pctx)

HTML

<a href="/listings/portofcontext--pctx"><img src="/api/listings/portofcontext--pctx/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

# 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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 177 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <img src=".github/assets/logo.png" alt="PCTX Logo" style="height: 128px">
  3. <h1>pctx</h1>
  4. [![Made by](https://img.shields.io/badge/MADE%20BY-Port%20of%20Context-1e40af.svg?style=for-the-badge&labelColor=0c4a6e)](https://portofcontext.com)
  5. [![NPM Version](https://img.shields.io/npm/v/%40portofcontext%2Fpctx)](https://www.npmjs.com/package/@portofcontext/pctx)
  6. [![Rust](https://img.shields.io/badge/rust-1.89%2B-green.svg)](https://www.rust-lang.org)
  7. [![Python](https://img.shields.io/pypi/v/pctx-client?color=blue)](https://pctx.readthedocs.io/en/latest/)
  8. </div>
  9. <div align="center">
  10. The open source framework to connect AI agents to tools and mcp with [Code Mode](#what-is-code-mode)
  11. </div>
  12. <div align="center">
  13. <br>
  14. <sub>— &nbsp; T R U S T E D &nbsp; B Y &nbsp; —</sub>
  15. <br><br>
  16. <a href="https://goose-docs.ai/docs/guides/managing-tools/code-mode/"><picture><source media="(prefers-color-scheme: dark)" srcset=".github/assets/block-logo-white.png"><img src=".github/assets/block-logo.png" alt="Block" height="22"></picture></a> &nbsp;&nbsp;&nbsp;&nbsp; <a href="https://www.sentient.xyz"><picture><source media="(prefers-color-scheme: dark)" srcset=".github/assets/sentient-logo-white.svg"><img src=".github/assets/sentient-logo.svg" alt="Sentient" height="22"></picture></a>
  17. </div>
  18. ## Install
  19. ```bash
  20. # Homebrew
  21. brew install portofcontext/tap/pctx
  22. # cURL
  23. curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/portofcontext/pctx/main/install.sh | sh
  24. # npm
  25. npm i -g @portofcontext/pctx
  26. ```
  27. ## Core Functionality
  28. pctx can be run as a scalable session server for Code Mode or as a lightweight unified MCP server that exposes Code Mode functionality for registered upstream MCP servers.
  29. ```bash
  30. # Start the Code Mode session server for the Python SDK
  31. pctx code-mode serve
  32. # Start Code Mode as a unified MCP server
  33. pctx code-mode init
  34. pctx code-mode dev
  35. ```
  36. ## Python SDK
  37. 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.
  38. ```bash
  39. pip install pctx-client
  40. ```
  41. ```python
  42. from pctx_client import Pctx, tool
  43. from agents import Agent # Use any Agent SDK
  44. from agents.run import Runner # This example is OpenAI Agents SDK
  45. @tool
  46. def get_weather(city: str) -> str:
  47. """Get weather information for a given city."""
  48. return f"It's always sunny in {city}!"
  49. pctx = Pctx(tools=[get_weather]) # or with mcp: servers=[your_mcp]
  50. tools = pctx.openai_agents_tools() # Run Code Mode with any Agent SDK
  51. agent = Agent(
  52. name="GreatCoder",
  53. model="litellm/openrouter/openai/gpt-oss-120b",
  54. instructions="You run code to complete complex tasks.",
  55. tools=tools,
  56. )
  57. ```
  58. ### Links
  59. - [Python SDK Quickstart and Docs](./pctx-py/README.md)
  60. - [Python API Reference](https://pctx.readthedocs.io/en/latest/)
  61. ## Node SDK
  62. Coming soon
  63. ## Unified MCP
  64. 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).
  65. ```bash
  66. # Initialize config for upstream mcp connections
  67. pctx code-mode init
  68. # Add HTTP or stdio MCP servers
  69. pctx code-mode add stripe https://mcp.stripe.com
  70. pctx code-mode add memory --command "npx -y @modelcontextprotocol/server-memory"
  71. # Start as HTTP server (dev mode with UI)
  72. pctx code-mode dev
  73. # Or start as stdio MCP server
  74. pctx code-mode start --stdio
  75. ```
  76. For complete CLI documentation, see [CLI.md](docs/CLI.md).
  77. For configuration options, see [Configuration Guide](docs/config.md).
  78. <img width="1020" height="757" alt="Screenshot 2025-11-21 at 11 03 20 AM" src="https://github.com/user-attachments/assets/d61be46d-5a4b-40fd-953a-7dc725266e63" />
  79. ## What is pctx?
  80. `pctx` sits between AI agents and MCP servers. It aggregates multiple upstream MCP servers, handles authentication, and exposes tools through a unified [Code Mode](#what-is-code-mode) interface. Instead of agents managing connections to individual MCP servers, they connect once to pctx.
  81. ## What is Code Mode?
  82. 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](https://www.anthropic.com/engineering/code-execution-with-mcp).
  83. **Traditional MCP flow**:
  84. 1. Agent calls `getSheet(id)`
  85. 2. Server returns 1000 rows → agent's context
  86. 3. Agent calls `filterRows(criteria)`
  87. 4. Server returns 50 rows → agent's context
  88. **With Code Mode**:
  89. ```typescript
  90. const sheet = await gdrive.getSheet({ sheetId: "abc" });
  91. const orders = sheet.filter((row) => row.status === "pending");
  92. console.log(`Found ${orders.length} orders`);
  93. ```
  94. **Result:** 98.7% reduction in tokens (150k → 2k) for this multi-step operation.
  95. ## Features
  96. - **Code Mode interface**: Tools exposed as code functions for efficient agent interaction. See [Code Mode Guide](docs/code-mode.md).
  97. - **Upstream MCP server aggregation**: Connect to multiple MCP servers through a single interface, with persistent upstream sessions across `execute_typescript` calls. See [Upstream MCP Servers Guide](docs/upstream-mcp-servers.md).
  98. - **Simple config with CLI**: Create the pctx.json config with a simple CLI. pctx.json manages auth, upstream MCPs, logging, and more. See [Config Guide](docs/config.md).
  99. - **Secure authentication**: Source secrets from environment variables, system keychain, and external commands. See [Authentication Section](docs/config.md#authentication) in the CLI configuration docs for more details.
  100. ## Security
  101. - LLM generated code runs in an isolated [Deno](https://deno.com) sandbox that can only access the network hosts specified in the configuration file.
  102. - No filesystem, environment, network (beyond allowed hosts), or system access.
  103. - MCP clients are authenticated in pctx. LLMs can never see your auth.
  104. ## Update
  105. Depending on the installation method (Homebrew/npm/cURL) the update method is different. Run `which pctx` if you are unsure what you used to install it.
  106. ```bash
  107. # Homebrew update
  108. brew upgrade pctx
  109. # cURL update
  110. pctx-update
  111. # npm update
  112. npm upgrade -g @portofcontext/pctx
  113. ```
  114. ## Develop
  115. - For core dev: install rust and jump into `crates/`
  116. - Client SDK dev: find the README in the SDK
  117. ## Learn More
  118. - [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
  119. - [Code execution with MCP by Anthropic](https://www.anthropic.com/engineering/code-execution-with-mcp)
  120. - [Code Mode explanation by Cloudflare](https://blog.cloudflare.com/code-mode/)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.