MCP Servers

processkit skills ship Python MCP servers that give agents mechanical correctness on top of probabilistic reasoning. For entity work, agents should use the MCP tools rather than hand-editing files: write tools validate schemas, enforce state machines, and append LogEntries where the server owns the side effect.

This Python implementation is intentional in v1. The native Rust CLI owns release trust and content lifecycle; it does not replace the MCP servers.

Status

The exact server inventory is release-generated and validated by the MCP manifest. Alpha.4 release acceptance exposes 199 gateway tools. Servers ship across processkit’s primitive, workflow, projection, routing, gateway, guard, and devops skills. Most ship default mcp-config.json fragments. aggregate-mcp remains an alternate compatibility entry point and does not register itself by default; context-archiving also ships a server script without a default config fragment.

Server scripts live under context/skills/<category>/<skill>/mcp/server.py. Processkit operation servers share a Python utility library at context/skills/_lib/processkit/.

The current direction is gateway first for harnesses that pay startup cost per stdio process. Per-skill servers remain canonical, but clients may register one gateway process instead of the granular set when they want one provider-neutral processkit tool surface.

processkit itself is usable without aibox. aibox is an installer and supervisor that can fetch processkit content, merge harness config, and manage a devcontainer. A user may also install the files by another method and point any MCP-capable harness at the shipped Python server commands directly.

Layer 0 — Foundation

Layer 1 — Identity

Layer 2 — Core entities

Layer 3 — Workflow and projections

Gateway

processkit-gateway is the provider-neutral gateway entry point. It can run as a direct stdio server, as a streamable HTTP daemon, or behind a lightweight stdio proxy for harnesses that only support command-backed MCP. Eager stdio remains the simplest mode. Daemon mode can use a catalog-backed lazy registration path so the gateway lists tools without importing every backing skill server at startup.

aggregate-mcp is the legacy one-process compatibility bridge. Both gateway surfaces keep unique tool names unchanged. If two source servers expose the same helper name, later duplicates are registered as <skill_slug>__<tool_name>.

Devops

Routing (cross-layer)

A standalone smoke test (no MCP transport, just direct function calls) runs all servers via:

uv run scripts/smoke-test-servers.py

Runtime requirements

Each MCP server is a standalone Python script using PEP 723 inline dependency metadata:

#!/usr/bin/env -S uv run
# /// script
# requires-python = ">=3.10"
# dependencies = ["mcp[cli]>=1.0,<2.0"]
# ///
from mcp.server.fastmcp import FastMCP
server = FastMCP("<skill-name>")
...
if __name__ == "__main__":
    server.run(transport="stdio")

Consumers need only Python ≥ 3.10 and uv — both already present in aibox containers. First run pays a small cost for uv to resolve and cache dependencies; subsequent runs are near-instant.

Cold offline preparation is not yet a supported guarantee. See the Python MCP runtime contract .

Transport

Per-skill servers and aggregate-mcp use stdio. processkit-gateway supports stdio and streamable HTTP:

uv run context/skills/processkit/processkit-gateway/mcp/server.py \
  serve --transport stdio

uv run context/skills/processkit/processkit-gateway/mcp/server.py \
  serve --transport streamable-http --host 127.0.0.1 --port 8000 \
  --path /mcp

uv run context/skills/processkit/processkit-gateway/mcp/server.py \
  stdio-proxy --url http://127.0.0.1:8000/mcp

The streamable HTTP daemon binds to localhost by default. Do not expose it on a non-local interface unless a deployment layer adds explicit authentication and network policy.

Configuration

Most skills that ship an MCP server include an mcp/mcp-config.json fragment:

{
  "mcpServers": {
    "<skill-name>": {
      "command": "uv",
      "args": ["run", "context/skills/processkit/<skill-name>/mcp/server.py"]
    }
  }
}

aibox init merges these fragments into the consuming project’s MCP config file. Harnesses that support gateway mode may register processkit-gateway instead of merging the per-skill fragments:

{
  "mcpServers": {
    "processkit-gateway": {
      "command": "uv",
      "args": [
        "run",
        "context/skills/processkit/processkit-gateway/mcp/server.py"
      ],
      "env": {
        "PROCESSKIT_MCP_MODE": "gateway"
      }
    }
  }
}

The install path is context/skills/processkit/<skill-name>/ — the processkit/ category subdirectory is part of the path. Provider-specific harness files (e.g. .mcp.json for Claude Code) are written by aibox at the right location for whichever harness the user picked.

Mode matrix

Which servers are mandatory

For per-skill registration, the following servers should always be registered regardless of package tier. Without them, agents cannot use the entity layer correctly:

The same tools may be reached through processkit-gateway or aggregate-mcp when a harness uses a one-process entry point.

Tier-specific servers (actor-profile, role-management, scope-management, gate-management, binding-management, model-recommender, and the workflow/projection servers) are registered based on the installed package tier. artifact-management and note-management are available in tiers that include their skills.

Compliance expectations

Agents should call route_task(task_description) before write-side processkit tool calls and use find_skill when a processkit skill might apply. Entity reads go through index-management; entity writes go through the owning management server. If a state change is not already logged by the MCP write tool, append a LogEntry with event-log.