CodexMCP

Personal MCP server that exposes a query_offload tool to Claude. Lets Claude delegate mechanical, output-heavy tasks (boilerplate, type generation, summarisation) to OpenAI while keeping reasoning in-context.

---

Setup

1. Install dependencies

npm install

2. Make codexmcp available globally

npm link

This creates a global codexmcp binary pointing at bin/codexmcp.js.

3. Configure environment

cp .env.example .env

Edit .env and fill in:

Variable	Description
TUNNEL_URL	Your Tailscale Funnel URL (e.g. https://t480.tail1234.ts.net)
JWT_SECRET	Any random 32+ character string
PORT	Port to listen on (default 3000)

Inference runs through the Codex CLI, not an OpenAI API key. Install it and run codex login (ChatGPT subscription) on the host machine before starting the server — query_offload shells out to codex exec.

4. Tailscale Funnel (T480)

Tailscale Funnel exposes a local port on a stable public HTTPS URL — no dynamic DNS, no port forwarding.

# On the T480, run once (survives reboots if you enable it):
tailscale funnel 3000

Get your permanent URL:

tailscale funnel status
# Example output: https://t480.tail1234.ts.net -> localhost:3000

Copy that URL into TUNNEL_URL in your .env.

5. Start the server

codexmcp

Expected output:

codexmcp running on http://0.0.0.0:3000
MCP endpoint (add to claude.ai): https://t480.tail1234.ts.net/mcp

6. Verify

curl http://localhost:3000/health
# {"status":"ok","server":"codexmcp","version":"0.0.1"}

7. Connect to claude.ai

1. Go to claude.ai → Settings → Connectors → Add custom connector
2. Paste your TUNNEL_URL/mcp (e.g. https://t480.tail1234.ts.net/mcp)
3. Complete the OAuth flow — it auto-approves (single-user server)

8. Create a Claude Project

1. Create a new Project in claude.ai
2. Add the codexmcp connector to it
3. Paste the system prompt below into Project Instructions

---

Permanent deployment with systemd (T480)

Copy the repo to the T480, install, link, and deploy the service:

# On T480
git clone <repo> ~/codexmcp
cd ~/codexmcp
npm install
npm link

# Copy and enable the service
sudo cp offload-mcp.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable offload-mcp
sudo systemctl start offload-mcp

# Check status
sudo systemctl status offload-mcp
journalctl -u offload-mcp -f

The ExecStart in offload-mcp.service points to /usr/local/bin/codexmcp (where npm link installs the global binary on Linux). Adjust if your npm prefix is different (npm prefix -g to check).

---

Claude Project system prompt

Paste this verbatim into the Project Instructions field:

## Behavior
- Never glaze. Be direct, honest, no sycophancy.
- Make no assumptions. Use the MCQ tool to clarify before proceeding. If skipped, pick the best option yourself.
- Format all responses carefully in clean markdown.
- Think before responding unless the query is trivial.
- When asked for opinions, be unbiased — say what is true, not what I want to hear.

## Task Routing
For every response, mentally split the task first:
1. Pure mechanical output (boilerplate, type generation, bulk code, summarizing large text, repetitive patterns) → call query_offload, return the result directly.
2. Mixed task (reasoning + output) → handle the reasoning yourself, call query_offload for the output part.
3. Pure reasoning (debugging, architecture, review, explanation) → answer directly, no tool call.
Call query_offload automatically. Never ask if you should use it.

---

Development

npm run dev   # node --watch src/server.js