pctx — MCP Aggregation & Code Mode

MCP aggregation and Code Mode execution layer for token-efficient agent workflows. Wraps portofcontext/pctx — connects agents to Linear, GitHub, and other MC...

Security Scan

The skill largely does what it says (wraps a local pctx MCP layer) but there are several inconsistencies and operational risks you should review before installing (macOS-only launchd usage, undeclared required tools, token storage/backups, and third-party brew/npm installs).

Purpose & Capability

The skill's name/description align with the scripts and SKILL.md: it wraps a local pctx server, manages MCP servers, and offers a Code Mode via a Deno sandbox. However the skill appears Mac-oriented (uses launchd/~/Library/LaunchAgents) while registry metadata lists no OS restriction. SKILL.md metadata also claims required tools (brew, npm, node) even though the registry 'required binaries' is empty — a mismatch that should be clarified.

Instruction Scope

Instructions and scripts operate on the local pctx endpoint (http://127.0.0.1:8080/mcp), config at ~/.config/pctx/pctx.json, and logs in /tmp. They also provide commands to add MCPs that accept environment-style secrets (LINEAR_API_TOKEN, GITHUB_PERSONAL_ACCESS_TOKEN). Adding MCPs will cause the skill to store credentials in the pctx config and create backups. The skill does not instruct reading unrelated system files, but it does manage files containing secrets (config and backups) and interacts with launchd — both are higher-impact actions than a pure read-only helper.

Install Mechanism

No centralized install spec in the registry, but included install.sh performs brew installs (portofcontext/tap/pctx, deno, github-mcp-server) and an npm global install (@tacticlaunch/mcp-linear). These are traceable package managers (brew and npm) rather than arbitrary downloads, which is lower risk, but you should verify the Homebrew tap and npm package authors before installing globally.

Credentials

The skill declares no required env vars, which matches the registry, but its documentation and runtime commands expect users to supply API tokens for MCPs (e.g., LINEAR_API_TOKEN, GITHUB_PERSONAL_ACCESS_TOKEN) when adding upstream servers. Those secrets will be saved in ~/.config/pctx/pctx.json and in automatic backups (copies created by cmd_config_backup). Backups are chmod 600, but they still persist on disk—this storage of credentials is a proportional but important sensitive side-effect that the user must accept.

Persistence & Privilege

The skill installs and expects a launchd plist at ~/Library/LaunchAgents/ai.openclaw.pctx.plist and loads/unloads it (start/stop/restart). That grants the skill a persistent local daemon on macOS. 'always' is false, and the skill does not modify other skills' configs, but the plist and daemon mean ongoing background network activity (the local MCP endpoint can proxy to external MCPs). Confirm you want a persistent agent and review the plist content before loading.

What to consider before installing

What to check before installing: - Confirm platform: the scripts use launchd (macOS). If you're not on macOS, the daemon/start logic won't work. - Review third-party sources: verify the Homebrew tap (portofcontext/tap) and the npm package (@tacticlaunch/mcp-linear) authors/URLs before running install.sh or npm install -g. - Secrets handling: adding MCPs will store API keys in ~/.config/pctx/pctx.json and create timestamped backups there. Decide whether you accept these files (they are chmod 600 but persist on disk); if not, avoid adding upstreams or ensure you have secure backup/cleanup policies. - Persistent daemon: inspect the launchd plist (~/Library/LaunchAgents/ai.openclaw.pctx.plist) before loading it. A running daemon exposes a local HTTP endpoint that can forward requests to external MCPs — understand and control which MCPs/endpoints you connect. - Local code execution: Code Mode runs user-supplied TypeScript in Deno; this enables powerful automation but also can execute arbitrary logic inside the sandbox. Limit which agents/users can send code to the /mcp endpoint. - Discrepancies to clarify with the publisher: SKILL.md frontmatter lists required tools (brew, npm, node) but the registry required binaries is empty, and the skill lacks an official install spec. Ask the maintainer to document supported OSes and to include a safe install manifest or package. If you proceed, run install.sh in a controlled environment, inspect the generated plist and ~/.config/pctx/pctx.json, and avoid adding upstream MCPs until you’ve reviewed the trustworthiness of their tokens and endpoints.

pctx — MCP Aggregation & Code Mode Execution

What is pctx?

pctx is a local server that:

1. Aggregates MCP servers — connects to Linear, GitHub, and other MCP backends behind one endpoint
2. Code Mode — instead of sequential tool calls, agents write TypeScript that runs in a Deno sandbox; only the result comes back (up to 98% token reduction on complex workflows)

Live endpoint: http://127.0.0.1:8080/mcp Connected MCPs: Linear (42 tools), GitHub (41 tools) Config: ~/.config/pctx/pctx.json Logs: /tmp/pctx.log | /tmp/pctx.err

---

When to use

• Agent needs to call Linear or GitHub tools via MCP
• Agent is doing multi-step tool workflows (pctx batches them into one TypeScript call)
• Any workflow where sequential tool calls return large intermediate payloads

---

Quick Start

# Check if pctx is running
{baseDir}/pctx-skill.sh status

# List connected MCP servers + tool counts
{baseDir}/pctx-skill.sh mcp-list

# Test a tool call
{baseDir}/pctx-skill.sh test linear linear_getOrganization
{baseDir}/pctx-skill.sh test github list_issues

---

Commands

Daemon Management

# Status — shows port, uptime
{baseDir}/pctx-skill.sh status

# Start daemon (launchd)
{baseDir}/pctx-skill.sh start

# Stop daemon
{baseDir}/pctx-skill.sh stop

# Restart
{baseDir}/pctx-skill.sh restart

MCP Server Management

# List all connected MCPs + tool counts + connection health
{baseDir}/pctx-skill.sh mcp-list

# Add an upstream MCP — examples:
# stdio MCP with npm package
{baseDir}/pctx-skill.sh mcp-add memory --command "npx" --arg "-y" --arg "@modelcontextprotocol/server-memory"

# stdio MCP with installed binary
{baseDir}/pctx-skill.sh mcp-add linear --command "mcp-linear" --env "LINEAR_API_TOKEN=your_token"

# HTTP MCP
{baseDir}/pctx-skill.sh mcp-add stripe https://mcp.stripe.com

# Remove an MCP
{baseDir}/pctx-skill.sh mcp-remove <name>

Config & Backup

# Backup pctx.json (always done automatically before mcp-add/remove)
{baseDir}/pctx-skill.sh config-backup

# Restore from backup (interactive if no timestamp given)
{baseDir}/pctx-skill.sh config-restore
{baseDir}/pctx-skill.sh config-restore 20260422-092733

Testing

# Test a specific MCP tool via pctx
{baseDir}/pctx-skill.sh test linear linear_getOrganization
{baseDir}/pctx-skill.sh test linear linear_getTeams
{baseDir}/pctx-skill.sh test github list_issues
{baseDir}/pctx-skill.sh test github get_file_contents

Install (idempotent)

# Run on new VMs or after full rollback
{baseDir}/install.sh

---

Calling pctx from Agent Code

The pctx server exposes an MCP endpoint at http://127.0.0.1:8080/mcp. Agents can call tools directly via JSON-RPC, or use Code Mode for batched TypeScript execution.

Simple tool call via curl

# Initialize + get session context
curl -s -X POST http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}'

# Call a tool (Code Mode — batched TypeScript)
curl -s -X POST http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"execute_typescript","arguments":{"script":"const org = await linear.linear_getOrganization({}); const teams = await linear.linear_getTeams({}); return { org, teams };"}}}'

Code Mode — batch multiple calls

The execute_typescript tool is the key feature. Write one script wrapped in async function run() that calls all tools needed:

Important: field name is code (not script). Code must be wrapped in async function run() { ... }.

Namespaces: Linear (capital L), Github (capital G, no 'b').

// BAD — multiple round-trips (traditional MCP)
const org = await Linear.linearGetOrganization({});
// ... agent receives result, burns tokens ...
const teams = await Linear.linearGetTeams({});
// ... agent receives result, burns tokens ...

// GOOD — one Code Mode call, one result
async function run() {
  const org = await Linear.linearGetOrganization({});
  const teams = await Linear.linearGetTeams({});
  const issues = await Linear.linearSearchIssues({ query: "urgent" });
  return JSON.stringify({ org, teams, issues }, null, 2);
}

// GitHub example
async function run() {
  const branches = await Github.listBranches({ owner: "MJM-Agents", repo: "rolling-reno-theme" });
  return JSON.stringify(branches, null, 2);
}

---

Currently Connected MCPs

Name	Binary	Transport	Auth	Tools
linear	mcp-linear	stdio	LINEAR_API_TOKEN	42
github	github-mcp-server stdio	stdio	GITHUB_PERSONAL_ACCESS_TOKEN	41

---

Rollback

Full rollback instructions: ROLLBACK-MCP-PCTX.md in workspace root.

Quick rollback — remove one MCP:

{baseDir}/pctx-skill.sh mcp-remove linear   # removes Linear, leaves GitHub
{baseDir}/pctx-skill.sh mcp-remove github   # removes GitHub, leaves Linear

Full nuclear rollback:

{baseDir}/pctx-skill.sh stop
brew uninstall pctx github-mcp-server
npm uninstall -g @tacticlaunch/mcp-linear
rm -rf ~/.config/pctx/ ~/Library/LaunchAgents/ai.openclaw.pctx.plist

---

Config

Variable	Default	Description
PCTX_CONFIG	~/.config/pctx/pctx.json	Path to pctx config
PCTX_PORT	8080	Port pctx listens on
PCTX_HOST	127.0.0.1	Host pctx binds to
PCTX_BIN	auto-detected	Path to pctx binary

---

Notes

• pctx.json is chmod 600 — contains API keys, never commit
• Deno sandbox: 10s execution timeout, no filesystem/env/system access
• OAuth not yet supported in pctx (v0.7.1) — remote Linear/GitHub MCPs require OAuth; use stdio/local for now
• Config auto-backed-up before every mcp-add / mcp-remove
• PAT registered under mjm-dex GitHub account — swap if needed