This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

MCP Servers

The gateway, per-skill servers, and the legacy aggregate bridge — plus what each harness supports.

1: Harness Compatibility

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.

Status

Twenty-nine MCP server scripts 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

Server	Tools
`index-management`	`reindex`, `query_entities`, `get_entity`, `search_entities`, `query_events`, `list_errors`, `stats`
`id-management`	`generate_id`, `validate_id`, `list_used_ids`, `format_info`
`event-log`	`log_event`, `query_events`, `recent_events`

Layer 1 — Identity

Server	Tools
`actor-profile`	`create_actor`, `get_actor`, `update_actor`, `deactivate_actor`, `list_actors`
`role-management`	`create_role`, `create_role_template`, `get_role`, `update_role`, `list_roles`, `link_role_to_actor`
`team-manager`	TeamMember identity, active interlocutor, consistency, and agent-card helpers

Layer 2 — Core entities

Server	Tools
`workitem-management`	`create_workitem`, `create_process_instance`, `create_sep_handoff`, `transition_workitem`, `query_workitems`, `get_workitem`, `link_workitems`
`decision-record`	`record_decision`, `transition_decision`, `query_decisions`, `get_decision`, `supersede_decision`, `link_decision_to_workitem`
`artifact-management`	`create_artifact`, `get_artifact`, `query_artifacts`, `update_artifact`
`note-management`	`prepare_hook_inbox_dirs`, `create_note`, `capture_inbox_item`, `claim_inbox_item`, `complete_inbox_item`, `fail_inbox_item`
`scope-management`	`create_scope`, `get_scope`, `list_scopes`, `transition_scope`
`gate-management`	`create_gate`, `create_gate_template`, `get_gate`, `list_gates`, `evaluate_gate`
`binding-management`	`create_binding`, `create_time_window`, `create_budget_application`, `end_binding`, `query_bindings`, `resolve_bindings_for`
`discussion-management`	`open_discussion`, `get_discussion`, `list_discussions`, `transition_discussion`, `add_outcome`
`migration-management`	`list_migrations`, `get_migration`, `start_migration`, `apply_migration`, `reject_migration`, `migrate_context_to_v2`
`model-recommender`	`list_models`, `get_profile`, `query_models`, `compare_models`, `get_pricing`, `check_availability`, `get_config`, `set_config`

Layer 3 — Workflow and projections

Server	Tools
`agent-card`	`project_agent_card`
`eval-gate-authoring`	`collect_run_outputs`, `codify_eval`, `calibrate_judge`, `bind_eval_to_runs`
`security-projections`	`project_agent_ids_rule`, `project_tetragon_tracing_policy`

Gateway

Server	Tools
`processkit-gateway`	`list_gateway_tools`, `gateway_health`, plus imported per-skill tools
`aggregate-mcp`	`list_aggregate_tools` plus imported per-skill tools

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

Server	Tools
`repo-management`	`detect_repo_provider`, `inspect_repo_state`, `list_repo_issues`, `list_repo_change_requests`, `plan_repo_reconcile`, `resolve_repo_issue`, `merge_change_request`, `commit_local_changes`, `push_current_branch`, `run_repo_reconcile`

Routing (cross-layer)

Server	Tools
`skill-finder`	`find_skill`, `list_skills`
`task-router`	`route_task` — returns skill + process override + MCP tool in one call
`skill-gate`	`acknowledge_contract`, `check_contract_acknowledged`, `skip_decision_record`

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.

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

Mode	Status	Process count	Best fit	Notes
Per-skill MCP servers	Canonical	Many	Fine-grained permissions and maximum compatibility	Each skill owns its server and config fragment.
`aggregate-mcp`	Compatibility	One	Existing one-process configs	Legacy bridge; not the preferred new gateway name.
`processkit-gateway` stdio	Current gateway	One	Claude Code, Codex, OpenCode, and other command-launching harnesses	Provider-neutral eager stdio server.
Daemon plus stdio proxy	Current gateway	One daemon plus lightweight proxies	Harnesses that restart stdio frequently	Requires a supervisor such as aibox or a user-managed daemon process.

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:

Server	Why mandatory
`index-management`	Entity discovery and full-text search
`id-management`	ID generation for all entity kinds
`workitem-management`	Work tracking
`discussion-management`	Structured deliberation
`decision-record`	Decision capture
`event-log`	Audit trail

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.

1 - Harness Compatibility

processkit’s MCP servers are provider-neutral Python programs. They do not require aibox at runtime. aibox can install processkit, merge MCP configuration, pre-authorize processkit tools where a harness supports that, and supervise a managed devcontainer. Those are convenience and lifecycle features; they are not a processkit dependency.

For a direct install, point the harness at the desired server command inside the installed context/skills tree. The recommended one-process entry point is:

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

Current modes

Mode	Use when	Harness impact
Per-skill servers	You need fine-grained tool registration or the broadest compatibility.	The harness launches one stdio process per registered skill.
`aggregate-mcp`	You already use the legacy aggregate server.	One stdio process, compatibility name, no daemon behavior.
`processkit-gateway` stdio	You want the provider-neutral gateway surface now.	One stdio process, eager tool import, richer gateway metadata.
Daemon plus stdio proxy	You want a long-lived daemon with lightweight harness proxies.	One shared daemon plus one lightweight stdio proxy per harness.

The current gateway command is equivalent to:

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

Daemon mode starts a localhost streamable HTTP MCP server:

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

Harnesses that only support stdio can connect through the proxy:

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

For lower daemon startup memory, generate a tool catalog and enable lazy registration:

uv run context/skills/processkit/processkit-gateway/mcp/server.py \
  catalog --write

PROCESSKIT_GATEWAY_IMPORT_MODE=lazy-catalog \
  uv run context/skills/processkit/processkit-gateway/mcp/server.py \
  serve --transport streamable-http

Harness notes

Harness	Recommended direction	Compatibility notes
Claude Code	Register `processkit-gateway` as an MCP stdio server, or keep per-skill servers when permission granularity matters.	Claude Code can launch command-backed MCP servers. aibox may also merge `.mcp.json`, settings, hooks, and preauthorization entries for managed projects.
Codex	Register `processkit-gateway` as an MCP stdio server.	Codex benefits from the one-process gateway because many per-skill stdio servers increase startup and approval overhead. Codex preauthorization support is narrower than Claude Code, so users may still see approval prompts depending on local policy.
OpenCode	Use stdio gateway mode when OpenCode is configured for MCP command servers.	Treat processkit as a normal MCP server command. aibox-specific supervision is optional and not required for direct use.
Hermes	Use stdio gateway mode when Hermes can launch MCP command servers.	The gateway is provider-neutral; Hermes-specific configuration should map the command and args exactly as shown above.
Aider	Use processkit skills and files directly; MCP gateway support depends on the surrounding Aider integration.	Aider is not a full MCP harness in the same sense as Claude Code or Codex. It may not enforce processkit tool-use contracts or call MCP tools without an adapter.

Choosing a mode

Use processkit-gateway stdio for the simplest one-process harness configuration. Use daemon plus stdio proxy when the environment can supervise one long-lived gateway process and the harness frequently restarts command-backed MCP servers. Use per-skill servers when a harness policy model needs separate permission surfaces. Keep aggregate-mcp only for existing configs that already depend on that server name.