//DOCS Runtime Engine

Punk Runtime Engine

Punk speaks MCP in both directions:

• Punk IS an MCP server. The Punk Runtime Engine side-loads Punk's runtime into your existing Claude Code (or Claude app) workflow: Claude stays the interface, Punk becomes the runtime underneath it. Your workflows, the semantic web, savings, approvals, and run explanations become native tools, and, optionally, every prompt you type lands in Punk as an observed, governed, auditable run.
• Punk CONSUMES MCP servers. A per-tenant registry of external MCP servers (stdio or http) backs tool_call workflow nodes, with governance and side-effect classification applied before any connection is made.

This page is the usage guide for both directions. Using Punk From Claude covers the first; Using MCP Servers From Punk covers the second.

Using Punk From Claude

The engine (apps/mcp, bun run mcp) is a stdio MCP server and a pure HTTP client of the gateway: it never touches storage directly, so it can point at any Punk deployment, local or remote.

Setup

Prerequisites: a running Punk gateway (bun run dev, default http://localhost:4100) and Bun on the machine running Claude Code.

One-liner (from anywhere — --cwd points at your Punk checkout):

claude mcp add punk -- bun run --cwd /path/to/punk mcp

Or per-project via .mcp.json at your project root:

{
  "mcpServers": {
    "punk": {
      "command": "bun",
      "args": ["run", "--cwd", "/path/to/punk", "mcp"],
      "env": {
        "PUNK_GATEWAY_URL": "http://localhost:4100",
        "PUNK_MCP_API_KEY": "pk_…(only when the gateway sets PUNK_API_KEY)"
      }
    }
  }
}

The engine inherits whatever its API key is allowed to do. Use a non-admin key unless you want approval decisions available in-conversation.

Verify the install without Claude:

PUNK_GATEWAY_URL=http://localhost:4100 bun run mcp --selfcheck

The selfcheck exercises the full tool surface against the live gateway through an in-process MCP client and exits non-zero on any failure.

The Nine Tools

Workflow runs triggered through the engine are real workflow runs (trigger mcp): node-level traces, cost/savings rollup, and the learning loop all apply, so repeated runs get cheaper (see Workflows).

Prompt Ingest Hook

An optional UserPromptSubmit hook (apps/mcp/hooks/ingest-prompt.sh) posts each Claude Code prompt to POST /api/v1/ingest/prompt. Install it in .claude/settings.json (project) or ~/.claude/settings.json (user):

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "PUNK_GATEWAY_URL=http://localhost:4100 sh /path/to/punk/apps/mcp/hooks/ingest-prompt.sh"
          }
        ]
      }
    ]
  }
}

Set PUNK_MCP_API_KEY in the same command string when the gateway requires auth.

What appears in the dashboard: each prompt becomes a completed observed run — provider claude-code, model external, route live, $0 cost, integrity-chained trace events — visible in the runs list, the audit trail, and savings accounting. The hook is fire-and-forget with a 1-second timeout and always exits 0. It can never block or slow down a prompt.

Privacy: the hook sends your prompt text to the Punk gateway, where it is stored in the trace ledger. Enable the gateway's redaction tenant setting first so emails, phone numbers, card numbers, and secret-shaped tokens are masked before they reach the ledger:

curl -X PUT http://localhost:4100/api/v1/settings \
  -H 'content-type: application/json' \
  -d '{"key": "redaction", "value": true}'

See Governance for what redaction masks.

Troubleshooting: Claude → Punk

Using MCP Servers From Punk

Punk consumes external MCP servers through a per-tenant registry. Registered servers back tool_call workflow nodes; every invocation is governance-checked with a classified side-effect level before any connection is made.

Registering Servers

Registrations are stdio (command, args?, env?) or http (url, headers?). Mutations require admin; create, delete, and test are audited. The dashboard manages all of this under Governance → MCP servers, or via the API:

A stdio server (the gateway spawns the command and speaks MCP over its stdio):

curl -X POST http://localhost:4100/api/v1/mcp/servers \
  -H 'content-type: application/json' \
  -d '{
    "name": "github",
    "transport": "stdio",
    "command": "bunx",
    "args": ["@modelcontextprotocol/server-github"],
    "env": { "GITHUB_TOKEN": "cred:cred_1a2b3c" }
  }'

An http server (streamable HTTP, with a one-shot SSE fallback for older servers):

curl -X POST http://localhost:4100/api/v1/mcp/servers \
  -H 'content-type: application/json' \
  -d '{
    "name": "internal-tools",
    "transport": "http",
    "url": "https://mcp.example.com/mcp",
    "headers": { "Authorization": "cred:cred_9f8e7d" }
  }'

Validation is strict: stdio requires a non-empty command, http requires url, and http URLs pass the same SSRF guard as web fetch (scheme and shape always; private/loopback/link-local/metadata destinations blocked when auth is enabled, with the open-dev carve-out for local work) at registration and again at connect time.

Credentials: cred:<id> References

Env and header values of the form cred:<id> resolve a stored credential at connect time — tenant-checked, inside the store boundary, never echoed by the API. Store the secret once, reference it forever:

curl -X POST http://localhost:4100/api/v1/credentials \
  -H 'content-type: application/json' \
  -d '{ "name": "github-bot", "provider": "github", "secret": { "value": "ghp_…" } }'
# → { "credential": { "id": "cred_1a2b3c", … } }   (the secret is never returned)

A credential's value key (or its sole key) replaces the reference. Credentials are AES-256-GCM encrypted at rest (PUNK_ENCRYPTION_KEY); see Workflows § Credentials.

OAuth Credentials And Auto-Refresh

Google-, GitHub-, and similar OAuth2 MCP servers hand out short-lived access tokens. Punk keeps them working by storing the full OAuth2 secret and refreshing it automatically — you never have to re-paste a token.

Store the OAuth shape (all string values — the vault holds string → string):

curl -X POST http://localhost:4100/api/v1/credentials \
  -H 'content-type: application/json' \
  -d '{ "name": "google-mcp", "provider": "google", "secret": {
        "access_token":  "ya29.…",
        "refresh_token": "1//…",
        "expires_at":    "1750000000000",
        "token_url":     "https://oauth2.googleapis.com/token",
        "client_id":     "…apps.googleusercontent.com",
        "client_secret": "…",
        "scope":         "https://www.googleapis.com/auth/drive.readonly"
      } }'

expires_at is the absolute expiry in epoch milliseconds. Reference the credential from the http server's Authorization header:

{
  "name": "google-drive",
  "transport": "http",
  "url": "https://mcp.example.com/sse",
  "headers": { "Authorization": "cred:cred_google" }
}

When the resolved credential has the OAuth shape, Punk sends Authorization: Bearer <access_token> and:

• Refreshes ahead of expiry. If expires_at is within 60 seconds at connect time, Punk exchanges the refresh token (grant_type=refresh_token POST to token_url) for a fresh access token before connecting.
• Refreshes on a 401. If the server rejects the token with an auth error, Punk refreshes once, reconnects, and retries the call — exactly once, so a genuinely revoked grant surfaces rather than looping.
• Re-encrypts the rotated secret. After any refresh, the new access_token / expires_at (and the rotated refresh_token, if the provider issued one) are written back into the credential vault, so the next call starts from the latest tokens.

The dashboard's Governance → Credentials form has an + OAUTH2 FIELDS button that pre-fills these keys. Non-OAuth cred:<id> references keep the existing value-key behavior unchanged.

Connection Testing

POST /api/v1/mcp/servers/:id/test connects (resolving any cred: references), lists tools, and persists status (ok/error), toolCount, and the last error onto the registration:

curl -X POST http://localhost:4100/api/v1/mcp/servers/mcp_…/test
# → { "ok": true, "toolCount": 12, "tools": [{ "name": "search_issues", … }], "latencyMs": 240 }

GET /api/v1/mcp/servers/:id/tools serves the tool list cached from the last test and re-lists live when it is older than 10 minutes. The dashboard's TEST button shows latency and tool chips inline.

Connections are pooled per server, closed after 5 idle minutes, and evicted whenever the registration changes — an edited server never keeps serving through a stale connection.

Binding Tools Into Workflows

A tool_call node binds a registered server's tool into a workflow graph. Config: serverId (required), tool (required), args (map of argument name → IRExpr), saveAs? (vars key, default tool). A concrete node:

{
  "id": "lookup",
  "kind": "tool_call",
  "next": "summarize",
  "config": {
    "serverId": "mcp_4d5e6f",
    "tool": "search_issues",
    "args": {
      "query": { "kind": "template", "template": "{{input.topic}} label:bug" },
      "limit": { "kind": "literal", "value": 5 }
    },
    "saveAs": "issues"
  }
}

The tool result lands in the vars environment under saveAs (structured content preferred, JSON-parsed text otherwise) and downstream nodes reference it like any other variable ({ "kind": "ref", "path": "issues" }). See Workflows for the full IR.

Governance And Side Effects

Before any connection is made, the gateway classifies the tool's side-effect level (declared level wins; otherwise the tool name is matched against verb heuristics — delete/pay-shaped names land at 4, send/create at 3, reads at 1, unknown names default to 3, conservative) and runs the governance check as agent workflow-engine with the action actionForTool derives (read:<resource> for levels ≤ 1, write:<resource> for 2–3, destroy:<resource> for 4).

• deny AND approval_required fail the node CLOSED — an unattended workflow cannot wait on a human.
• tool.called / tool.completed events (with the classified side-effect level) land on the workflow run's integrity-chained ledger.
• Policy checks and decisions are audited like every other governed action.

Endpoints

Troubleshooting: Punk → MCP Servers

Trust Boundaries

• A stdio registration executes its command on the gateway host. That is operator-level configuration, the same trust level that can set webhook URLs and promote artifacts, which is why every registry mutation is admin-gated. Do not register commands you would not run on the gateway host yourself.
• http URLs go through the same SSRF guard as web fetch at registration and again at connect time.
• Tool invocations from workflows are governance-checked first with classified side-effect levels; deny and approval_required fail the node closed.
• The Runtime Engine itself holds no secrets beyond its gateway API key and inherits whatever that key is allowed to do.