Unified AI System v0.3.2: a fail-closed, credential-free MCP gateway

[happy520ai]

Pre-submission Checklist

• This post follows the MCP community guidelines

What would you like to share?

I built an open, terminal-first AI gateway that runs as a credential-free local MCP server for Codex and other stdio hosts. The current release is io.github.happy520ai/unified-ai-system@0.3.2 in the official MCP Registry.

The MCP surface exposes eight tools:

• gateway_chat, gateway_health, gateway_readiness
• knowledge_readiness
• workflow_actions, workflow_health
• workforce_agents, workforce_health

The default path is deliberately deterministic. The MCP process starts an isolated local gateway backed by a fake provider, proves that real-provider mode is disabled before serving tools, rechecks that boundary before chat, and removes the managed process when the MCP session ends. Contributors can therefore reproduce a complete initialize -> tools/list -> tools/call path without an account or API key.

Try it with Codex

codex mcp add unified-ai-system -- docker run --rm -i ghcr.io/happy520ai/unified-ai-system/mcp-server:0.3.2

The same image works as a generic stdio server:

docker run --rm -i ghcr.io/happy520ai/unified-ai-system/mcp-server:0.3.2

The implementation lesson that changed our release test

Our first dedicated container launched through pnpm mcp. A package-manager lifecycle banner reached stdout before the server response and corrupted JSON-RPC framing, even though source-level tests were green.

The released image now invokes the Node entrypoint directly. The verification harness talks to the image's actual default command, performs MCP initialize, initialized, tools/list, and tools/call, checks all eight tools, proves executionMode: fake and realProviderCallsMade: false, and verifies both container and child-gateway teardown.

The reusable pattern is small:

• Treat stdout as protocol-only for stdio servers.
• Test the package's real default command, not only a command override.
• Gate tool exposure on an observable safety invariant.
• Recheck cost-bearing boundaries at call time.
• Verify process teardown as part of the protocol contract.

v0.3.2 adds stable repository metadata and a project icon for MCP discovery, places the one-command Codex path first, and pins public examples to reproducible container tags. It remains a public engineering preview, not a production-readiness or autonomy claim.

Relevant Links

• GitHub repository: https://github.com/happy520ai/unified-ai-system
• Official MCP Registry entry: https://registry.modelcontextprotocol.io/v0.1/servers/io.github.happy520ai%2Funified-ai-system/versions/0.3.2
• v0.3.2 release: https://github.com/happy520ai/unified-ai-system/releases/tag/v0.3.2
• MCP server documentation: https://github.com/happy520ai/unified-ai-system/tree/master/packages/mcp-server
• 60-second Codex guide: https://github.com/happy520ai/unified-ai-system/blob/master/docs/codex-mcp-quickstart.md
• Current CI: https://github.com/happy520ai/unified-ai-system/actions/runs/30562779777
• Published-image verification: https://github.com/happy520ai/unified-ai-system/actions/runs/30562779815

I would value feedback on the boundary between read-only gateway inspection and future approval-gated mutation tools. Which gateway operation would be useful enough to expose through MCP, and what evidence or approval should it require?