Manifold

Manifold

One interface. Many connections. Manifold.

English | 日本語

Manifold is a gateway that acts as an MCP server while connecting to multiple external MCP servers and OpenAPI / Swagger-compliant REST APIs on the backend.

Why "Manifold"?

The name Manifold comes from an engine's intake manifold.

An intake manifold is the component that distributes air and fuel evenly and efficiently from a single inlet to multiple cylinders. We named this project Manifold because its structure is similar.

Architecture

flowchart TD

client["MCP Client"] --> manifold["Manifold (this server)"] manifold --> mcp["External MCP Servers"] manifold --> rest["OpenAPI / Swagger REST API Servers"] manifold --> a2a["A2A Agents"]

Features

• OpenAPI / Swagger → MCP conversion: Automatically generates MCP tools from OpenAPI 3.x / Swagger 2.x specifications
• Static tool catalog: Inspect the MCP tools an OpenAPI spec would generate before starting the gateway (manifold openapi tools), and start from a committed, diffable generated file instead of fetching the spec at boot (manifold openapi generate, mcpServers. .tools.file)
• Breaking-change detection: Classify upstream spec changes as breaking or not with oasdiff, mapped to the affected MCP tools (manifold openapi diff, manifold openapi generate --check)
• MCP backend aggregation: Transparent reverse proxy to external MCP servers, relaying their tools and prompts
• Tool filtering and renaming: Expose only the tools you need, under the names and descriptions you choose (mcpServers. .tools.include / exclude / overrides)
• Audit log: Write one JSON line per tool call (audit)
• A2A agents as MCP servers: Expose an A2A (Agent2Agent) agent's Agent Card skills as MCP tools, either served on their own (agents) or attached to a service (mcpServers. .agents, skills exposed as __ tools next to the service's own tools), with the caller's session id carried as the A2A contextId and the response context returned in _meta.a2a
• Built-in OAuth 2.1 server: Authorization server with PKCE (S256) support. Downstream clients register through DCR (RFC 7591) or a client ID metadata document (CIMD), and can be mapped one-to-one onto upstream OAuth clients
• Pluggable backend authentication: Choose one of static header (authValue) / OAuth 2.0 (oauth2) / API key Token Exchange (tokenExchange) / Google service account (googleServiceAccount)
• MCP Apps: Passes MCP Apps (io.modelcontextprotocol/ui) UIs of MCP backends through to hosts that support them — _meta.ui on tools, and the ui:// resources via resources/list / resources/read — and strips them for hosts that don't (mcpServers. .apps)
• Resource links: Stores binary content from tool responses (including format: binary fields inside JSON responses) in S3 and returns download URLs (resource links)
• Lazy connection (stdio) / stateless connection (http): stdio backends connect on first request (no backend dependency at gateway startup); http backends open a fresh connection per request and never share a session across callers
• Selectable storage: Session / token management in memory (default), Redis or SQLite
• OpenTelemetry support: OTLP export of traces, metrics, and logs (metrics also support Prometheus-style pull)

Requirements

• Nothing else for the prebuilt binary or Docker image. Go 1.26+ to build from source
• Optional: Redis or SQLite, to keep sessions and OAuth tokens across restarts or share them between replicas. Without either, Manifold keeps them in memory

Installation

Download binary

Download the latest binary from Releases.

Build from source

git clone https://github.com/nonchan7720/manifold.git

cd manifold go build -o manifold .

Docker

docker pull ghcr.io/nonchan7720/manifold:latest

Usage

Start the gateway

# Run the binary

manifold gateway

Specify a config file explicitly (-c / --config, config name without extension)

manifold gateway -c config

Run from source

go run main.go gateway

Docker (working directory is /home/nonroot)

docker run -p 9999:9999 \ -v $(pwd)/config.yaml:/home/nonroot/config.yaml \ ghcr.io/nonchan7720/manifold:latest

Docker Compose (development)

Starts a development environment including Redis.

docker compose up -d

Ready-to-run configuration examples are available in the examples/ directory.

Inspect and generate MCP tools

For OpenAPI-mode servers (spec and/or tools.file configured), manifold openapi shows what the gateway would register, and can write it to a file the gateway starts from — without ever fetching the spec at boot.

# Print the tools every OpenAPI-mode server would register (no gateway started)

manifold openapi tools -c config

One server, with the full inputSchema

manifold openapi tools -c config --server petstore --json

Write the generated tools file for every server that has tools.file configured

(errors for a server that has no spec configured)

manifold openapi generate -c config

CI: fail if the committed file doesn't match the live spec, without writing anything

manifold openapi generate -c config --check

Show breaking changes between the committed file and the live spec (oasdiff)

manifold openapi diff -c config

openapi tools output:

SERVER    TOOL          OPERATION          DESCRIPTION

petstore addpet POST /pet Add a new pet to the store. petstore getpetbyid GET /pet/{petId} Find pet by ID.

The generated file (tools.file) is YAML, with a diffable tools section followed by the resolved spec:

version: 1

generatedBy: manifold 1.12.0 source: spec: https://petstore3.swagger.io/api/v3/openapi.json sha256: "..." fetchedAt: "2026-09-04T00:00:00Z" format: openapi3 tools:

• name: getpetbyid operation: GET /pet/{petId} description: Find pet by ID. binaryResponse: false inputSchema: { ... }

spec: { ... } # openapi3 document, external $refs internalized

Binary fields and responses

A format: binary property in a multipart/form-data, application/x-www-form-urlencoded or application/json request body (for Swagger 2, type: file form parameters and format: binary fields inside an in: body schema, including nested objects, arrays, $ref and allOf) is not exposed as a plain string. It becomes a oneOf that accepts either a string (base64 content or a URL to fetch the file from) or an object naming the source explicitly (url / base64 / text / content, plus optional filename and contentType), and carries _meta.manifold.file: true so clients can recognize it as a file input. An operation whose success response is binary (e.g. image/png, application/octet-stream) is marked binaryResponse: true; at runtime such responses are handled as binary content and, when storage is configured, returned as resource links (see storage). Only a successful (2xx) response whose actual Content-Type is not textual is treated as binary: error responses, 3xx responses and text/JSON/XML/YAML bodies (including +json / +xml types) are returned as-is even for a binaryResponse: true tool. From a spec with one upload and one download operation:

tools:

• name: uploadfile operation: POST /files description: Upload a file binaryResponse: false inputSchema: properties: file: _meta: manifold: file: true fileInputHint: 'Provide the file content as a base64-encoded string, or as a URL (e.g. a presigned URL) to download the file from. For explicit control, an object may be passed instead with one of these keys: {url:"..."} ...' description: File to upload oneOf:
• description: Base64-encoded file content, or a URL (e.g. a presigned URL) to download the file from. type: string
• description: Explicit file source; provide exactly one of url/base64/text/content. properties: base64: { type: string, description: Base64-encoded file content. } url: { type: string, description: URL to download the file content from. } text: { type: string, description: Raw (non-base64-encoded) text file content. } content: { type: string, description: Legacy auto-detected base64 or URL content. } filename: { type: string, description: Filename to use for the upload. } contentType: { type: string, description: MIME content type to use for the upload. } type: object label: _meta: {} description: "" type: string required:
• file type: object
• name: downloadfile operation: GET /files/{fileId}/content description: Download a file binaryResponse: true inputSchema: properties: fileId: description: "" type: string required:
• fileId type: object

In a JSON request body, a binary field's value is resolved the same way (base64, URL or explicit object) and sent to the upstream API as base64. Conversely, a format: binary field inside a 2xx JSON response (Swagger 2: format: binary or type: file; nested objects and arrays included, OpenAPI 3.1 contentMediaType used as the content type) is uploaded to storage when it is configured: the base64 value in the JSON is replaced with its download URL, and a resource link is added to the result for each uploaded field. Without storage, or for null / non-base64 values, the JSON is returned unchanged.

Recommended workflow:

1. Add tools.file to the server's config (see mcpServers. .tools) and run manifold openapi generate -c config.
2. Commit the generated file. Its tools section makes upstream spec changes reviewable as a normal PR diff.
3. Start the gateway (manifold gateway -c config) — it reads the tools from the file, with no network access to spec at startup.
4. After the upstream spec changes, re-run manifold openapi generate -c config and commit the update. A stale file (spec changed but the file wasn't regenerated) fails gateway startup with an error telling you to regenerate.
5. Add manifold openapi generate -c config --check as a CI step, so a PR that changes the upstream spec without regenerating the file fails before merge.

CI: --check only checks servers with tools.file configured — a server without one is skipped with a stderr note, and --server restricts the check to a single server. For each, it rebuilds the catalog from the live spec and compares it against the committed file: source.sha256 (the upstream spec's raw bytes), the tools section, and the embedded spec section (the internalized document the gateway actually runs from) — generatedBy a