Skip to content

cloudg MCP internals

From docs/MCP_INTERNALS.md on GitHub

A contributor's guide to cloudg/mcp/: what each file does, the contracts between the pieces, how a request is dispatched, how each adapter and the native server work inside, how to add tools and adapters, and how the test suite is organized. Read MCP.md first for the user-facing behavior; this document assumes it.

Companion documents:

Outputs quoted here were produced by running the code on the branch feature-mcp-layer (cloudg 0.6.0, Python 3.13, mcp 2.3.0 unless stated otherwise).

Sections

  • 1. Ground rules

    These hold across the package, and reviews check for them.

  • 2. Package map

    init.py re-exports the names most programs need (CloudGMCPLayer, CallInfo, Principal, ToolContext, the spec and content classes, the five error classes,...

  • 3. Core contracts

    All four specs inherit _BaseSpec:

  • 4. Inside the layer

    CloudGMCPLayer.init (layer.py):

  • 5. Inside the adapters

    detect_server_kind(server) checks, in order: NativeMCPServer instance; any class in the MRO named FastMCP from a module whose top package is fastmcp; a type...

  • 6. Inside the native server

    valid_id accepts strings and integers (not booleans or null). dumps produces compact single-line JSON, which stdio framing needs.

  • 7. server.py and cli.py

    create_layer_from_options loads the config (config or config_path), takes the default registry or the one given, applies read_only_registry when asked,...

  • 8. Adding a tool, resource, template or prompt

    The steps, then a complete module and its tests. The example was run from outside the repo (module and test in a scratch directory, -p tests.mcp.conftest to...

  • 9. Writing a new adapter or transport

    There are two ways in, depending on whether the target speaks MCP itself.

  • 10. Tests

    On the branch with mcp 2.3.0 and no fastmcp, the suite gave 823 passed, 6 skipped, 834 warnings in 89.51s. The skips are the mcp 1.x and fastmcp sections.

  • 11. Known quirks and open questions

    Found while writing this guide, and still present after the fixes that followed it (each re-checked by running it). The earlier list also had items about...