Manifold MCP Server

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

MCP Client
    │
    ▼
┌─────────────┐
│   Manifold  │   ← this server
└─────────────┘
    │       │
    ▼       ▼
External  OpenAPI / Swagger
MCP       REST API Server
Server

Features

• OpenAPI / Swagger → MCP conversion: Automatically generates MCP tools from OpenAPI 3.x / Swagger 2.x specifications
• MCP backend aggregation: Transparent reverse proxy to external MCP servers
• Built-in OAuth 2.1 server: Authorization server with PKCE (S256) support
• Pluggable backend authentication: Choose one of static header (authValue) / OAuth 2.0 (oauth2) / API key Token Exchange (tokenExchange)
• Resource links: Stores binary content from tool 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 backed by Redis or SQLite
• OpenTelemetry support: OTLP export of traces, metrics, and logs (metrics also support Prometheus-style pull)

Requirements

• Go 1.26+
• Redis or SQLite (for session management)

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.

Configuration

Place a configuration file (config.yaml) in the current directory or in a config/ subdirectory. Configuration values support environment variable expansion in the form ${VAR} or ${VAR:-default}.

Connecting to an MCP backend

Expose an external MCP server through Manifold.

gateway:
  port: 9999
  # openssl rand -base64 32
  encryptKey: ${ENCRYPT_KEY}

mcpServers:
  my-mcp-server:
    description: External MCP server
    transport: http
    url: http://localhost:8080/mcp

sqlite:
  path: ./tmp/manifold.db

Connecting to an OpenAPI / Swagger backend

Automatically generate MCP tools from an OpenAPI specification.

gateway:
  port: 9999
  encryptKey: ${ENCRYPT_KEY}

mcpServers:
  my-api:
    description: Sample REST API
    spec: https://example.com/api/openapi.json
    baseURL: https://example.com

OpenAPI backend with OAuth 2.0 authentication

gateway:
  port: 9999
  encryptKey: ${ENCRYPT_KEY}

mcpServers:
  my-api:
    description: OAuth-protected API
    spec: https://example.com/api/openapi.json
    baseURL: https://example.com
    oauth2:
      clientID: YOUR_CLIENT_ID
      clientSecret: YOUR_CLIENT_SECRET
      authURL: https://example.com/oauth/authorize
      tokenURL: https://example.com/oauth/token
      scopes:
        - read
        - write

redis:
  addrs:
    - "${REDIS_ADDRS:-localhost:6379}"
  db: ${REDIS_DB:-0}

Configuration reference

gateway

gateway.specRefresh

Periodically re-fetches the specs of OpenAPI mode servers (mcpServers.<name>.spec) and updates the MCP tool definitions without restarting Manifold. Added tools are registered, removed tools are unregistered, and connected clients are notified via notifications/tools/list_changed.

gateway:
  specRefresh:
    interval: 5m

Changes are detected by hashing the fetched spec document, so a change made only in an externally $ref-ed document leaves the hash unchanged and is not picked up. When a fetch or parse fails, the existing tool definitions are kept and the next interval retries.

mcpServers.<name>

Server names (<name>) are used in URL paths, so only alphanumerics, _, and - are allowed.

authValue / oauth2 / tokenExchange are mutually exclusive; only one may be configured at a time.

mcpServers.<name>.oauth2

mcpServers.<name>.tokenExchange

Exchanges the API key received from the client for an OAuth token at the specified token exchange endpoint, and uses it for backend requests. Exchange results are cached, and rate limits (429) are respected.

redis

sqlite

Either redis or sqlite must be configured.

storage

Stores content included in OpenAPI/Swagger tool responses (images, binaries, etc.) in external storage and returns resource links (download URLs). When unset, no storage is used.

storage:
  type: s3
  hostURL: https://manifold.example.com
  s3:
    bucket: my-bucket
    keyPrefix: manifold/media

fileFetch

When a URL is passed to a file input field of an OpenAPI/Swagger tool, Manifold downloads the file from that URL. As an SSRF countermeasure, connections to private/loopback/link-local IPs and the http:// scheme are rejected by default.

Each field can also be overridden via environment variables (FILEFETCH_MAXSIZE, FILEFETCH_ALLOWLOCAL, FILEFETCH_ALLOWEDHOSTS).

fileFetch:
  allowLocal: false
  maxSize: 524288000 # 500MiB
  # allowedHosts:
  #   - example.com
  #   - files.example.com:8443

telemetry

Output settings for traces, metrics, and logs via OpenTelemetry.

For the http / grpc exporters, specify addr (host:port) or url, plus an optional headers map of extra request headers (e.g. for a SaaS OTLP endpoint that requires an Authorization header). grpc also accepts insecure. With metrics.exporterType: pull, Prometheus-format metrics are exposed at the /metrics endpoint instead of OTLP push.

headers can also be supplied as a single environment variable holding a JSON object, instead of a nested YAML map — useful when the value (e.g. a bearer token) is injected at deploy time rather than checked into config.yaml:

telemetry:
  trace:
    http:
      url: ${OTEL_EXPORTER_OTLP_TRACES_ENDPOINT}
      headers: ${OTEL_EXPORTER_OTLP_HEADERS_JSON}

export OTEL_EXPORTER_OTLP_HEADERS_JSON='{"Authorization":"Basic xxxxx"}'

telemetry:
  serviceName: manifold
  trace:
    enabled: true
    grpc:
      addr: localhost:4317
      insecure: true
  metrics:
    enabled: true
    exporterType: push
    grpc:
      addr: localhost:4317
      insecure: true
  logs:
    enabled: true
    grpc:
      addr: localhost:4317
      insecure: true

Tool authorization (OPA sidecar)

Manifold can enforce which server/tool pairs a caller may use on tools/call and tools/list, delegating each decision to an external OPA sidecar. Disabled by default (authz.enabled: false, preserving prior behavior); authentication, group resolution, and policy storage stay out of Manifold's scope — it trusts identity headers injected by an upstream layer and queries OPA for the decision.

authz:
  enabled: true
  opaURL: http://localhost:8181
  timeout: 3s
  decisionPath:
    list: /v1/data/mcp/authz/allowed_tools
    call: /v1/data/mcp/authz/allow
    catalog: /v1/data/mcp/authz/allow_catalog
  headers:
    userID: x-user-id
    userGroups: x-user-groups
  input:
    user: user
    groups: groups
    server: server
    tool: tool
    tools: tools
    toolName: name
    fromHeaders:
      tenant:
        header: x-tenant-id
        required: true

Manifold treats the headers.userID value as an opaque string: it doesn't interpret it, just passes it through as-is to the key authz.input.user names in the decision input (default user). In a multi-tenant deployment, use a format that includes the tenant (e.g. {tenant}:{user}) so policies can tell tenants apart — or use input.fromHeaders instead (see "Multi-tenant policy data" below), in which case headers.userID doesn't need to carry the tenant. headers.userGroups values should likewise be immutable opaque IDs (e.g. ULIDs) rather than display names, since display names can change.

input lets a policy author match an existing decision-input contract instead of renaming their policy to Manifold's defaults. Keys that appear together in the same input object must be pairwise distinct: user / groups / server / tool (the tools/call input), user / groups / tools (the tools/list input), and server / toolName (each tools/list array element) — startup validation rejects a collision within any of those groups. Every key must also be non-empty. input.fromHeaders field names must likewise be non-empty and must not collide with any of the (possibly renamed) top-level keys above — user / groups / server / tool / tools. The comparison is case-sensitive, since OPA input keys are: with the defaults in place, a field named User is accepted because input.user is a different key. toolName is not reserved: it only names a key inside the tools array elements, never a top-level one. The same header may be assigned to more than one field.

Prerequisites

Manifold trusts headers.userID / headers.userGroups — and, if configured, headers.bypass and every header named in input.fromHeaders — on every request without verifying them itself, the same caveat as the WebMCP reverse gateway's forwardAuth mode (see its Trust boundary section in docs/design/webmcp-reverse-gateway.md). Before enabling authz.enabled:

• The fronting proxy must strip or overwrite any client-supplied headers of the same names, so a caller cannot forge its own identity
• Direct access to Manifold bypassing that proxy must be blocked at the network layer (e.g. a Kubernetes NetworkPolicy)
• headers.bypass is more sensitive than the identity headers: a caller that can set it to true disables authorization entirely for its own requests, regardless of identity or group membership. The fronting proxy must strip or overwrite it with the same rigor, and every network path that can reach Manifold without going through that proxy must be closed at the network layer — not merely authenticated separately

Decision contract

Manifold POSTs {"input": ...} to opaURL + decisionPath.call for every tools/call, to opaURL + decisionPath.list once per tools/list (batched across every tool, not queried per tool), and to opaURL + decisionPath.catalog for every GET /mcp/list?tools=true. The examples below use the default authz.input key names; every key is renameable (see the input table above):

// tools/call
{"input": {"user": "user-042", "groups": ["team-finance"], "server": "billing-svc", "tool": "create_invoice"}}
// → {"result": true}

// tools/list
{"input": {"user": "user-042", "groups": ["team-finance"], "tools": [{"server": "billing-svc", "name": "create_invoice"}, ...]}}
// → {"result": [{"server": "billing-svc", "name": "create_invoice"}, ...]}

// GET /mcp/list?tools=true
{"input": {"user": "user-042", "groups": ["team-finance"]}}
// → {"result": true}

Manifold does not prescribe a shape for OPA's data document; policies are free to structure it however they like — see examples/opa/ for a working policy.rego and data.json (data.policies[<group id>].tools as a list of <server>/<tool> glob patterns, data.policies[<group id>].catalog as a boolean).

Multi-tenant policy data

input.fromHeaders maps a decision-input field name to an inbound HTTP header, so a value the upstream identity layer already knows (a tenant ID, a region) reaches the policy without being encoded into headers.userID. Every configured field is resolved for every decision kind (tools/call, tools/list, and GET /mcp/list?tools=true) and added as a top-level field alongside user / groups / etc.:

authz:
  input:
    fromHeaders:
      tenant:
        header: x-tenant-id
        required: true
      roles:
        header: x-roles
        required: false
        type: list
      seat_count:
        header: x-seat-count
        type: number

// tools/call
{"input": {"user": "user-042", "groups": ["team-finance"], "server": "billing-svc", "tool": "create_invoice", "tenant": "acme", "roles": ["admin", "auditor"], "seat_count": 42}}

type controls the JSON type the raw header value becomes:

required defaults to true — omitting the key keeps the fail-closed behavior of the identity headers. With required: false, a missing or empty header (or a list with no non-blank element) leaves the field out of the decision input entirely rather than sending an empty value, so a policy should guard it:

# input.roles is absent on requests that carried no x-roles header, so read
# it through a default instead of indexing it directly.
roles := object.get(input, "roles", [])

That tenant field lets data be organized per tenant instead of flat, so one bundle can serve every tenant without a naming convention baked into user:

package mcp.authz

default allow := false

allow if {
	tenant_policies := data.tenants[input.tenant].policies
	some group in input.groups
	some pattern in tenant_policies[group].tools
	glob.match(pattern, ["/"], sprintf("%s/%s", [input.server, input.tool]))
}

This replaces the {tenant}:{user} convention described above for headers.userID — with input.fromHeaders resolving the tenant explicitly, headers.userID only needs to identify the user within that tenant.

Distributing per-tenant data

Manifold only knows opaURL and decisionPath.*; how policy and data reach the sidecar is OPA's concern (see "Operating recommendations" below for serving them as a bundle over HTTP). Once data is keyed by tenant, you can choose how finely to split it:

flowchart LR
    M[Manifold] -->|"POST /v1/data/mcp/authz/allow<br/>input.tenant = acme"| O[OPA sidecar]
    O -.->|poll| B[(bundle service)]
    B -.->|"mcp-authz/policy.tar.gz<br/>roots: mcp/authz"| O
    B -.->|"tenants/acme/bundle.tar.gz<br/>roots: tenants/acme"| O
    B -.->|"tenants/globex/bundle.tar.gz<br/>roots: tenants/globex"| O

One OPA can load several bundles, each owning a disjoint subtree of data, so a tenant's policy data can be published and rolled back independently of every other tenant's. The OPA side of that looks like:

services:
  bundles:
    url: https://bundles.example.com
bundles:
  policy:
    service: bundles
    resource: mcp-authz/policy.tar.gz
  tenant-acme:
    service: bundles
    resource: tenants/acme/bundle.tar.gz
  tenant-globex:
    service: bundles
    resource: tenants/globex/bundle.tar.gz

Each bundle's .manifest declares the subtree it owns; the Rego above keeps reading data.tenants[input.tenant] unchanged.

// mcp-authz/policy.tar.gz
{"revision": "2026-08-29-01", "roots": ["mcp/authz"]}
// tenants/acme/bundle.tar.gz
{"revision": "2026-08-29-01", "roots": ["tenants/acme"]}

Three constraints follow from how OPA merges bundles:

• Roots must not overlap. OPA refuses to activate a bundle whose root conflicts with another's (["tenants"] alongside ["tenants/acme"], for example), so splitting means splitting every tenant, and shared data cannot live in the same subtree as tenant-specific data
• Splitting is not isolation. Every bundle still lands in the one data tree of the one OPA process, so a policy that reads data.tenants.globex can. The tenant boundary is enforced by the policy indexing through input.tenant; bundle boundaries only scope updates and blast radius
• Adding a tenant is an OPA config change. bundles: is static, so each new tenant needs the sidecar reconfigured. OPA's discovery feature can distribute the bundle list itself, at the cost of another moving part, and every bundle polls independently, so very large tenant counts do not scale gracefully this way

The alternative is to not share the sidecar at all: run one Manifold + OPA pair per tenant. Then the sidecar is the tenant, data needs no tenant level, and there is nothing for input.fromHeaders to resolve.

Tool catalog for policy authoring

Writing a policy requires knowing every <server>/<tool> pair that exists, but tools/list only ever shows what the caller is already allowed to see. GET /mcp/list?tools=true returns the unfiltered catalog instead: when authz.enabled is false it's open to anyone, and when true it queries decisionPath.catalog the same way tools/call queries decisionPath.call — identified by headers.userID / headers.userGroups, and denying (403 {"error": "forbidden"}) on a missing identity, a policy deny, or a Decider error, without ever falling back to a static allowlist.

{
  "mcp": [
    {
      "name": "petstore",
      "description": "Swagger Petstore sample API",
      "tools": [
        {"name": "getpetbyid", "description": "Find pet by ID."}
      ]
    },
    // A WebMCP reverse server's tools only exist per-browser-connection, so
    // it reports "dynamic" instead of a tool list.
    {"name": "billing-svc", "description": "browser app", "dynamic": true},
    // A backend that failed to connect still lists (with "error" instead of
    // "tools") rather than dropping out of the response.
    {"name": "crm", "description": "CRM MCP backend", "error": "connect: dial tcp: connection refused"}
  ]
}

Disabling authorization per tenant

A fronting proxy that multiplexes several tenants behind one Manifold deployment can disable authz for a single request without flipping authz.enabled globally: set headers.bypass (default x-authz-bypass) to the exact string true. Any other value — True, 1, empty, or the header missing — goes through the normal authz checks (fail-closed).

When bypassed, for that request:

• tools/call skips OPA and reaches the tool directly
• tools/list returns the backend's full tool list, unfiltered
• GET /mcp/list?tools=true returns 200 with the full catalog without querying decisionPath.catalog

This is equivalent to authz.enabled: false for that one request. Manifold logs decision: bypass (with server / method, no identity — none was resolved) so bypassed requests are distinguishable from allow / deny in an audit trail.

Fail-closed behavior

Every ambiguous or failing case denies the request rather than allowing it:

• A missing or empty headers.userID / headers.userGroups denies without querying OPA
• A missing or empty header for a required field configured in input.fromHeaders denies the same way, without querying OPA. required defaults to true; a field with required: false is omitted from the input instead of denying
• An input.fromHeaders value that doesn't parse as its configured type (e.g. type: number on a non-numeric header) denies without querying OPA, regardless of required
• A non-200 response, a response missing the expected result field, a timeout, or a connection failure to OPA all deny
• tools/list filtering is a convenience — it hides tools the caller cannot use so they don't clutter a client's tool picker — but it is not the enforcement point. Enforcement happens on tools/call; a client that already knows a tool's name (e.g. from a stale list) is still denied there
• A reverse (WebMCP) mcpServers entry always registers a create_pairing_code tool (see docs/design/webmcp-reverse-gateway.md), and authz.enabled covers it like any other tool. A group that should be able to pair with such a server needs <server>/create_pairing_code in its policy, or pairing itself is denied
• This also holds one level down, inside OPA itself: if a bundle fetch fails, OPA keeps enforcing with the last bundle it activated — a bundle server outage stops policy updates, not decisions. But if OPA has never activated a bundle since startup (the bundle server was unreachable at boot, for example), data stays empty and every decision comes back false / [], which fail-closes the same way. Bundle fetch failures are still worth alerting on — see "Operating recommendations" below

Operating recommendations

• Enable OPA's decision log for an audit trail of every allow / allowed_tools / allow_catalog query. Each event should carry the decision, the same fields Manifold sent in that decision's input, and the revision of the policy data that produced it — without a data revision there's no way to tell which policy version a given decision was made under. The input fields differ per decision kind (see "Decision contract" above); the names below are the authz.input defaults, each of which is renameable:

  Decision	Query	Input fields
  allow	tools/call	user, groups, server, tool
  allowed_tools	tools/list	user, groups, and a tools array of {server, name} entries
  allow_catalog	GET /mcp/list?tools=true	user, groups

  Every input.fromHeaders field that resolved is present in all three, at the top level. A field with required: false is absent from the input on requests whose header was missing or empty, so a decision log missing it is expected rather than a dropped field.

• Distribute policy and data as an OPA bundle served over HTTP rather than mounting local files, so policy updates don't require restarting the sidecar. Bundle mode also stamps every decision log event with bundles.<name>.revision, which is where that revision comes from

• Monitor OPA's bundle fetch status (see "Fail-closed behavior" above for what a failure does to enforcement): OPA's Health API (GET /health?bundles=true) reports unhealthy until every configured bundle has been activated at least once, so it doubles as a readiness probe. The status API and decision log also surface fetch failures

See examples/opa/ for a runnable OPA sidecar with sample policy and data.

HTTP endpoints

The HTTP endpoints exposed by Manifold.

MCP

OAuth 2.1

Other

Development

See CONTRIBUTING.md for how to set up a development environment and submit changes.

Test

make test

Lint

make lint

Inspiration

This project is inspired by the Agent / MCP Gateway of LiteLLM.

Just as LiteLLM's MCP Gateway provides a unified access point to multiple MCP servers, Manifold aims to be a gateway that connects a single MCP interface to many MCP servers / REST APIs.

License

MIT License