Unified AI System MCP Server
Connect Codex and other MCP hosts to the credential-free Unified AI System
preview over stdio.
The server starts an isolated local gateway automatically, pins it to the
deterministic fake provider, exposes eight tools, and removes the gateway when
the MCP session ends. It does not enable or authorize real provider calls.
| Tool | Behavior |
|---|
gateway_health | Inspect gateway health and provider safety state. |
gateway_readiness | Inspect first-run and chat readiness. |
gateway_chat | Send one fake-provider-only chat request. |
knowledge_readiness | Inspect local knowledge infrastructure. |
workflow_health | Inspect the governed workflow subsystem. |
workflow_actions | List workflow action definitions. |
workforce_health | Inspect the workforce subsystem. |
workforce_agents | List workforce agent descriptors. |
All inspection tools are read-only. The chat tool checks the gateway safety
state before every request and fails closed unless realProviderEnabled is
exactly false and the response proves executionMode: "fake".
Run From Source
From the repository root:
pnpm install --frozen-lockfile
node packages/mcp-server/src/index.js
The project-level .codex/config.toml registers
that command automatically in trusted Codex projects. Restart Codex after
cloning or changing MCP configuration, then use /mcp to inspect the server.
Add To Codex With Docker
No clone or API key is required:
codex mcp add unified-ai-system -- docker run --rm -i ghcr.io/happy520ai/unified-ai-system/mcp-server:0.3.2
The dedicated image starts the MCP server by default; no command override is
required, and it invokes Node directly so package-manager output cannot pollute
the JSON-RPC stream. Its OCI identity and stdio transport are declared in the
repository root server.json for the official MCP
Registry.
The equivalent config.toml entry is:
[mcp_servers.unified_ai_system]
command = "docker"
args = [
"run",
"--rm",
"-i",
"ghcr.io/happy520ai/unified-ai-system/mcp-server:0.3.2",
]
startup_timeout_sec = 45
tool_timeout_sec = 60
default_tools_approval_mode = "writes"
Try It In Codex
Restart Codex after adding the server, then run /mcp verbose to confirm that
all eight tools are connected. A useful first task is:
Use the Unified AI System MCP tools to check gateway health and readiness,
then send MCP_READY through gateway chat only if the gateway proves
fake-only mode. Report the provider, model, execution mode, and response.
The 60-second Codex MCP quickstart
includes two more safe tasks, expected evidence, diagnostics, and the removal
command.
Connect To An Existing Safe Gateway
Set AI_GATEWAY_MCP_URL to use an already running instance:
AI_GATEWAY_MCP_URL=http://127.0.0.1:3100 node packages/mcp-server/src/index.js
Startup is rejected if that gateway may call a real provider. Authentication
and real-provider execution are intentionally outside this preview surface.
Verify
The test launches the server through the official MCP v2 client, completes the
stdio handshake, lists all eight tools, calls every tool, proves fake-provider
chat, closes the client, and confirms that the managed gateway stopped: