Unified Ai System MCP Server

Unified AI System

Run and govern models, agents, knowledge, and tools through one open gateway. The first verified request needs no account or API key; real providers remain explicit opt-in and human authority stays inside the execution path.

Connect Codex Through MCP

Run the gateway as a local MCP server with one anonymous container command:

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

Restart Codex, then use /mcp to inspect eight tools for gateway health, readiness, fake-provider chat, knowledge, workflows, and workforce status. A trusted source checkout also includes project-level Codex configuration, so the direct Node entrypoint is discovered without maintaining a second config.

The dedicated MCP image starts its own isolated gateway and removes it when the session ends. It fails closed if a gateway may call a real provider. See the MCP server guide, the active official Registry entry, and its source metadata in server.json.

One-Command Demo

With Docker installed, run the complete terminal demo without cloning the repository:

docker run --rm ghcr.io/happy520ai/unified-ai-system/ai-gateway-service:0.3.2 pnpm gateway demo

The container starts an isolated gateway, verifies health, sends one fake-provider chat request, prints the result, and removes itself. It never calls a real provider.

To run the same path from source:

git clone https://github.com/happy520ai/unified-ai-system.git
cd unified-ai-system
corepack enable
corepack prepare pnpm@9.15.4 --activate
pnpm install --frozen-lockfile
pnpm gateway demo

The Codespaces button prepares Node.js 22, pnpm 9.15.4, and the workspace dependencies in a browser terminal. Its container configuration pins the gateway to fake-provider mode; run pnpm gateway demo after setup completes.

Operate From The Terminal

The source checkout includes a real terminal interface rather than only a scripted screenshot:

# Terminal 1
pnpm gateway serve

# Terminal 2
pnpm gateway status
pnpm gateway chat "Hello from Unified AI System"
pnpm gateway doctor

demo, status, chat, doctor, and version support --json. The chat command refuses to send when a real provider may be active unless the operator adds --allow-real-provider explicitly for that request. Read the CLI reference for commands, exit codes, and safety behavior.

Run The Gateway

Run the public container:

docker run --rm --publish 3100:3100 \
  ghcr.io/happy520ai/unified-ai-system/ai-gateway-service:0.3.2

Call it directly from another terminal:

curl --request POST http://127.0.0.1:3100/chat \
  --header "content-type: application/json" \
  --data "{\"prompt\":\"Hello from Unified AI System\"}"

The default runtime uses a deterministic local fake provider. Terminal and API workflows are the public product surface; no browser UI is required or exposed by default.

What You Get

Why It Is Different

• A control plane, not another chat skin. Models, agents, knowledge, tools, permissions, and evidence belong in one governed execution path.
• Useful before cloud configuration. A fresh clone and the public container can prove the complete local path without provider credentials.
• Human authority is architectural. Real execution is explicit, observable, interruptible, and designed to remain accountable.

Read the longer project vision and the public roadmap.

If this is the kind of open AI infrastructure you want to exist, star the repository and join the Codex MCP launch discussion.

Run From Source

Requirements:

• Node.js 22 recommended; Node.js 20 or newer supported.
• pnpm 9.15.4 or newer.
• Git.

git clone https://github.com/happy520ai/unified-ai-system.git
cd unified-ai-system
corepack enable
corepack prepare pnpm@9.15.4 --activate
pnpm install --frozen-lockfile
pnpm verify:public-clone
pnpm gateway demo
pnpm gateway serve

Useful local endpoints:

• Health: http://127.0.0.1:3100/health/check
• Setup readiness: http://127.0.0.1:3100/setup/readiness

Architecture

flowchart LR
    H["Human intent"] --> W["Terminal, API, and MCP"]
    W --> G["Governance and approval"]
    G --> R["AI Gateway"]
    R --> M["Model routing"]
    R --> A["Agents and workforce"]
    R --> K["Knowledge and context"]
    R --> T["Tools and automation"]
    M --> L["Local fake provider"]
    M -. "explicit opt-in" .-> P["External providers"]
    A --> E["Evidence and observability"]
    K --> E
    T --> E
    E --> H

The system is currently a modular monolith: one deployable gateway with clear internal ownership boundaries and reusable workspace packages. See the architecture guide for details.

Honest Boundaries

Real provider calls are disabled by default. Begin with .env.example and the provider guide, and never commit credentials.

Verify The Project

pnpm check
pnpm test
pnpm check:public
pnpm verify:public-clone
pnpm verify:mcp

Every push to master runs Linux CI and a real container startup smoke test. The container path checks health, setup readiness, the terminal-only public surface, fake-provider chat, the MCP handshake, tool discovery, and managed process cleanup before the multi-architecture image is published.

Build With Us

The project is early enough for focused contributions to shape its foundations. Current entry points include:

• Add a credential-free JavaScript chat example
• Document how to add and test a provider adapter
• Help shape the next terminal-first CLI commands

Read CONTRIBUTING.md, join Discussions, or send a focused pull request. Security reports belong in SECURITY.md.

Repository Map

apps/
  agent-console/          Terminal CLI and operator interaction
  ai-gateway-service/     Main gateway runtime and HTTP API
packages/
  mcp-server/             Codex-ready stdio MCP server
  ...                     Contracts, SDKs, configuration, and engines
docs/                     Public user and architecture documentation
tools/                    Maintained repository and runtime checks

Historical phase documents and generated evidence stay off master. The pre-cleanup engineering history remains available on the archive branch.

Project Links

• Official MCP Registry entry
• v0.3.2 Discovery Metadata
• v0.3.1 MCP Registry Distribution
• v0.3.0 Terminal and Codex MCP Preview
• v0.2.0 Terminal CLI Preview
• Codex MCP server
• Documentation
• Roadmap
• Vision
• Support
• Launch kit

If this direction is useful, star the repository so more builders can find it, then tell us what the next trustworthy capability should be.

Licensed under Apache-2.0.