kaos-mcp

Part of Kelvin Agentic OS (KAOS) — open agentic infrastructure for legal work, built by 273 Ventures. See the full KAOS package map for the rest of the stack.

kaos-mcp is the FastMCP runtime and server bridge of KAOS — it mounts any KaosRuntime into the official Python MCP SDK and exposes its tools, content / tabular / session / config resources, and structured log stream over stdio or streamable HTTP. Tool annotations, ToolResult envelopes, per-request _meta.kaos_config overrides, and kaos.* log records flow through the bridge unchanged so MCP clients (Claude Code, Codex, Gemini, Cursor, VS Code, custom agents) see exactly the contract documented by kaos-core. The package also ships the unified kaos management CLI used by every sibling module for doctor / status / setup / serve.

The base install is intentionally small: seven runtime dependencies (httpx, kaos-content[markdown], kaos-core, mcp[cli], pydantic, pydantic-settings, starlette) and no compiled native code. There are no optional extras at this release — every adapter (tools, resources, content templates, tabular templates, config resource, session resource, log bridge, dynamic logging/setLevel, workflow prompts) is included in the base install. Sibling KAOS modules are not runtime dependencies of kaos-mcp; you bring your own KaosRuntime and register whichever modules you have installed.

Install

uv add "kaos-mcp>=0.1.0"
# or
pip install "kaos-mcp>=0.1.0"

kaos-mcp requires Python 3.13 or newer (3.14 is supported). The package is pure Python, classified Operating System :: OS Independent — it runs anywhere CPython 3.13+ runs (Linux, macOS, Windows).

Quick start

Build a runtime, register a sibling module's tools, and serve them over stdio (the transport Claude Code, Codex, and Gemini use by default):

from kaos_core import KaosRuntime
from kaos_pdf import register_pdf_tools

from kaos_mcp import KaosMCPServer, KaosMCPSettings

# 1. Build a runtime and register the tools you want exposed.
runtime = KaosRuntime()
register_pdf_tools(runtime)            # 7 read-only kaos-pdf-* tools

# 2. Configure the server. Every field is overridable via KAOS_MCP_*
#    environment variables or per-request _meta.kaos_config.
settings = KaosMCPSettings(
    name="kaos-pdf-mcp",
    instructions="PDF extraction tools backed by pypdfium2.",
    transport="stdio",
)

# 3. Run the server. run_stdio() blocks; run_streamable_http() boots
#    a Starlette app on settings.host:settings.port mounted at
#    settings.streamable_http_path (default /mcp).
server = KaosMCPServer(runtime=runtime, settings=settings)
server.run_stdio()                     # for Claude Code / Codex / Gemini
# server.run_streamable_http()         # for HTTP / browser-based clients

KaosMCPServer is the high-level entry point. If you need direct access to the underlying FastMCP app — for example to mount it inside an existing Starlette / FastAPI service — call create_app(runtime, settings) instead and embed the returned app yourself.

Concepts

The package is a thin, typed bridge between kaos-core and the Python MCP SDK. The most important entries:

CLI

kaos-mcp ships two console scripts. Both support --json on every structured subcommand for piping into other agents.

kaos — the unified KAOS management CLI used by every sibling module. Health checks, status, agentic-environment configuration, and a smart serve that auto-detects installed modules:

kaos doctor --json                              # environment + credential check
kaos status --json                              # module + server inventory
kaos setup claude --scope project               # write .mcp.json
kaos setup codex                                # write ~/.codex/config.toml
kaos setup gemini --scope user                  # write ~/.gemini/settings.json
kaos serve --module pdf,web,office              # stdio with selected modules
kaos serve --http --port 8000                   # streamable HTTP, all installed

Project scaffolding (kaos new ...) lives in the separate kaos-ui package — install it and use kaos-ui new <kind> <name> to scaffold FastAPI / Streamlit / Next.js apps.

kaos-mcp — the bare server entry point. Use it when you want a single-process MCP server with explicit module loading and no management overhead:

kaos-mcp serve --module pdf                     # stdio, single module
kaos-mcp serve --module pdf,web --http          # streamable HTTP
kaos-mcp list-tools --json                      # registered tools
kaos-mcp list-resources --json                  # registered resources

Without --module, kaos-mcp serve starts with an empty runtime and prints guidance on how to load tools. Module-specific entrypoints (kaos-pdf-serve, kaos-web-serve, ...) are preferred for single-module use; kaos-mcp serve is the right choice when you want to compose several modules into one server.

Compatibility & status

Documentation

Per-package reference: see in-tree docstrings and CHANGELOG.md.

Cross-cutting KAOS guides (agentic patterns, persona presets, settings policy, citations, MCP data flow, migration to 0.1.0 GA) live in kaos-modules/docs/guides/.

Companion packages

kaos-mcp is one of the packages in the Kelvin Agentic OS. The broader stack:

Packages depend on kaos-core; everything else is opt-in. Mix and match the ones you need.

Development

git clone https://github.com/273v/kaos-mcp
cd kaos-mcp
uv sync --group dev

Install pre-commit hooks (recommended — they run the same checks as CI on every commit, scoped to staged files):

uvx pre-commit install
uvx pre-commit run --all-files     # one-time full sweep

Manual QA commands (the same set CI runs):

uv run ruff format --check kaos_mcp tests
uv run ruff check kaos_mcp tests
uv run ty check kaos_mcp tests
uv run pytest tests/unit -q

Build from source

uv build
uv pip install dist/*.whl
python -c "import kaos_mcp; print(kaos_mcp.__version__)"  # smoke import

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for setup, quality gates, pull request expectations, and engineering standards. By contributing you agree to follow the project conduct expectations and certify the Developer Certificate of Origin v1.1 — sign every commit with git commit -s. Please open an issue before starting on a non-trivial change so we can align on scope.

Security

For security issues, please do not file a public issue. Report privately via GitHub Private Vulnerability Reporting or email security@273ventures.com. See SECURITY.md for the full disclosure policy.

License

Apache License 2.0 — see LICENSE and NOTICE.

Copyright 2026 273 Ventures LLC. Built for kelvin.legal.