Bridge OpenAPI to MCP

Operation to tool mapping

Each publishable OpenAPI operation becomes one MCP tool, deterministically.

• Name. The tool name is the operation's operationId. Without one, the bridge falls back to "{METHOD} {path}", for example GET /v1/quotes. Fallback names are stable within one spec version and can shift between versions, so give operations explicit ids.
• Input schema. Path and query parameters become top-level properties of one JSON Schema object, and a request body becomes a single property named body holding the body schema whole. Required parameters and a required body stay in the schema's required list. Header and cookie parameters are skipped (crates/protocol/chio-openapi/src/generator.rs:181-186), so the dispatcher supplies required headers. Keep upstream credentials and operator-selected tenant identity in the host, and expose only parameters the agent is authorized to choose.
• Output schema. The generator takes the 200 response schema, then 201, then the first other 2xx that declares one (generator.rs:233-256), as the tool's outputSchema. Agents that honor output schemas validate responses with it.
• Description. The operation's summary if present, otherwise its description, otherwise a synthesized "{METHOD} {path}". A present summary wins outright; the two are never concatenated.
• Route binding. The bridge keeps a BTreeMap<String, RouteDispatch> keyed on tool name. Each entry holds a RouteBinding of method and path template, the query parameters, and whether a body is required, so at invoke time the bridge rebuilds the exact method and URL. Path parameters are percent-encoded and substituted into the template from the tool arguments.

Side-effect classification

The bridge classifies each tool by HTTP method into the has_side_effects flag the kernel uses for side-effect admission. A read classification grants nothing: this host issues named grants for its read operations too.

A read served over POST, common in search-style RPC-over-REST designs, is classified as a side effect by default. Mark it with x-chio-side-effects: false.

OpenAPI extensions

chio-openapi reads these x-chio-* fields on an operation.

• x-chio-publish: false. Omits the operation from the tool manifest entirely, for admin or internal routes.
• x-chio-side-effects. An explicit boolean that overrides the method-based classification.
• x-chio-sensitivity. A data classification, one of public, internal, sensitive, or restricted, default internal. The guard pipeline uses it for logging level and audit granularity; it leaves policy unchanged.
• x-chio-approval-required: true. Sets annotations.requires_approval on the generated tool and makes the operation deny by default, ahead of every other policy input. The approval comes from a person: chio approvals pending, then chio approve <id>.
• x-chio-budget-limit. A per-invocation cost cap in minor currency units, for example 5000, which the budget guard applies against the caller's remaining budget.

paths:
  /v1/quote:
    post:
      operationId: quote
      x-chio-side-effects: true
      x-chio-approval-required: true   # deep discounts wait for a person
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuoteRequest'
      responses:
        '201':
          description: Quote issued
  /admin/reprice:
    post:
      operationId: reprice
      x-chio-publish: false   # never exposed as a tool

What the receipt and the tool result carry

Every hash on a bridged receipt is bare lowercase hex, 64 characters, with no ed25519: or 0x prefix, and the id is content-addressed over the canonical body. The classification fields receipt_kind, boundary_class, tool_origin, redaction_mode, and trust_level are always present. The HTTP method, path template, and status live in the MCP tool result's structuredContent, beside the parsed upstream body.

pub(crate) fn bridged_tool_response(binding: &RouteBinding, response: BridgedResponse) -> Value {
    let text = serde_json::to_string(&response.body).unwrap_or_else(|_| "{}".to_string());
    json!({
        "content": [{
            "type": "text",
            "text": text,
        }],
        "isError": response.is_error,
        "structuredContent": {
            "httpStatus": response.status,
            "method": binding.method,
            "path": binding.path,
            "body": response.body,
        }
    })
}

path is binding.path, the OpenAPI template, so GET /v1/quotes/{quoteId} reports /v1/quotes/{quoteId} for every quote. The dispatcher received the expanded URL; the receipt binds the arguments that produced it.

A denial has the same structure with "decision": { "verdict": "deny" } and the failing guard in evidence[].guard_name. Read the guard there: the kernel formats decision.reason from the name of its registered guard (crates/kernel/chio-kernel/src/kernel/dispatch.rs:401-407), which for a composed pipeline is the literal guard-pipeline (crates/guards/chio-guards/src/pipeline.rs:59-61). A pre-dispatch denial prevents the HTTP call; a failure found after dispatch leaves open whether the upstream was contacted.

The dispatcher contract

The bridge opens no socket itself. A registered bridge performs its HTTP operation through the dispatcher your host supplies, which keeps the crate transport-agnostic and testable, and it enforces the caller-supplied HttpEgressContract around every dispatch: URL and DNS pre-flight before the call, a response-byte ceiling after. The dispatcher owns transport; the contract owns egress policy.

/// Invoke a bridged tool. A dispatcher is required so the kernel cannot
/// sign successful receipts for simulated side effects.
pub fn invoke_tool(&self, tool_name: &str, arguments: Value) -> Result<Value, BridgeError> {
    let dispatch = self
        .route_dispatches
        .get(tool_name)
        .ok_or_else(|| BridgeError::ToolNotFound(tool_name.to_string()))?;

    if let Some(dispatcher) = &self.dispatcher {
        let binding = dispatch.binding();
        let url = dispatch_url(&self.config.base_url, dispatch, &arguments)?;
        // HttpEgressContract: gate the dispatcher invocation on the typed
        // egress contract. The bridge stays transport-agnostic, so we
        // validate URL and DNS pre-flight, then enforce the response-byte
        // ceiling post-dispatch. Missing contract state fails closed.
        let contract = enforce_dispatch_contract(self.config.egress_contract.as_ref(), &url)?;
        let response = dispatcher(&binding.method, &url, &arguments)?;
        enforce_no_redirect_response(&response)?;
        enforce_bridged_response_body(contract, &response)?;
        Ok(bridged_tool_response(binding, response))
    } else {
        Err(BridgeError::Kernel(
            "OpenAPI bridge requires a dispatcher for live tool invocation".to_string(),
        ))
    }
}

With no dispatcher set, every invocation returns BridgeError::Kernel carrying OpenAPI bridge requires a dispatcher for live tool invocation and fails closed, so the kernel never signs a successful receipt for a side effect that never happened. A missing egress contract makes enforce_dispatch_contract return OpenAPI bridge dispatcher requires an HttpEgressContract, and a response without observed_body_bytes makes enforce_bridged_response_body refuse the same way.

use chio_openapi_mcp_bridge::{BridgeError, BridgedResponse, HttpDispatcher};
use std::io::Read;

pub const RESPONSE_LIMIT: u64 = 128 * 1024;

// The bridge expands declared path/query parameters. This dispatcher sends
// only arguments.body as JSON, and never follows an ungoverned redirect.
pub fn build() -> anyhow::Result<Box<HttpDispatcher>> {
    let client = reqwest::blocking::Client::builder()
        .redirect(reqwest::redirect::Policy::none())
        .no_proxy()
        .timeout(std::time::Duration::from_secs(10))
        .build()?;
    Ok(Box::new(move |method, url, arguments| {
        let execute = || -> anyhow::Result<BridgedResponse> {
            let method = reqwest::Method::from_bytes(method.as_bytes())?;
            let mut request = client.request(method, url);
            if let Some(body) = arguments.get("body") {
                request = request.json(body);
            }
            let response = request.send()?;
            let status = response.status().as_u16();
            let mut bytes = Vec::new();
            response.take(RESPONSE_LIMIT + 1).read_to_end(&mut bytes)?;
            anyhow::ensure!(
                bytes.len() as u64 <= RESPONSE_LIMIT,
                "response exceeds 128 KiB"
            );
            let body = if bytes.is_empty() {
                serde_json::Value::Null
            } else {
                serde_json::from_slice(&bytes)?
            };
            Ok(BridgedResponse {
                status,
                body,
                observed_body_bytes: Some(bytes.len() as u64),
                is_error: status >= 400,
            })
        };
        execute().map_err(|error| BridgeError::UpstreamError(error.to_string()))
    }))
}

This dispatcher disables redirects, uses the exact local upstream with no proxy, applies a 10-second timeout, and stops reading above 128 KiB. It sends arguments.body as the JSON request body; the bridge has already expanded declared path and query parameters. The bridge rejects a returned 3xx, so the dispatcher returns redirects as they arrive. A test may install a dispatcher that returns a canned BridgedResponse with observed_body_bytes and a valid egress contract; it exercises mapping and response checks, and the pricing walkthrough covers HTTP delivery and recorded quotes.

Checks on the generated tools

• bridge.tool_names(). Every operation you expected became a tool, and none marked x-chio-publish: false did. A missing name is a spec problem.
• bridge.route_binding(name). The method and path template the bridge dispatches. Compare it with the spec path.
• manifest().tools[i].has_side_effects. The classification the kernel admits on. A search endpoint served over POST reads true until you annotate it.
• manifest().tools[i].input_schema. Whether an agent can reach every argument. Header and cookie parameters are absent by construction.

from_spec validates eagerly. A spec whose publishable operations all resolve to nothing returns ManifestError::EmptyManifest, and a path template whose parameters disagree with the declared parameters fails at construction. Run OpenApiMcpBridge::from_spec against your spec in CI to catch construction errors, and test authorization, dispatch, and application state separately.

Bridge errors

Missing contracts and malformed arguments fail before HTTP dispatch. Redirect and response-size failures occur after the upstream was contacted, and a failed result cannot roll back a write the upstream already performed.

• OpenAPI bridge requires a dispatcher for live tool invocation. No set_dispatcher call. Install the HTTP dispatcher before serving client calls.
• OpenAPI bridge dispatcher requires an HttpEgressContract. egress_contract: None. Populate it; no permissive default exists.
• HttpEgressContract rejects bridge URL: .... The resolved URL failed scheme, authority, or DNS pre-flight. Widen allowed_authority_set deliberately, or fix the base_url.
• OpenAPI bridge dispatcher must provide observed_body_bytes for response-size enforcement. The dispatcher returned a BridgedResponse with that field unset. Set it from the raw body length, before JSON parsing.
• OpenAPI bridge dispatchers must not follow redirects; returned HTTP redirect status .... The dispatcher returned a 3xx. Disable redirect following in the client; a client that hides intermediate redirects breaks the contract and can evade this check.
• OpenAPI bridge missing required request body `body`. The operation declares a required body and the arguments had no body key, or it was null.
• OpenAPI bridge path parameter `x` must not be a dot segment. An argument resolved to . or ... The empty-string case has its own message. Both refuse before the URL is built.
• OpenAPI bridge route path `/x/{y}` contains undeclared path parameter `y`. A construction-time error: the template names a parameter the operation does not declare. The mirror case, a declared parameter absent from the template, has its own message.

The dispatcher refusal is at crates/protocol/chio-openapi-mcp-bridge/src/lib.rs:280-282, the four egress and transport checks at dispatch.rs:171,175,186,198, the body check at dispatch.rs:252, the two path-parameter checks at dispatch.rs:393,398, and the two construction-time template checks at dispatch.rs:121,128. All arrive as BridgeError, which the kernel wraps as KernelError::ToolServerError when the bridge is registered as a tool server.

Spec, response, and credential rules

• Responses. The bridge models each response as one JSON body, and this host buffers it within its bound. Server-sent events and long-lived streams sit outside it, and the HTTP proxy buffers responses the same way.
• Spec versions. The bridge reads OpenAPI 3.0 and 3.1. Convert Swagger 2.0 first, for example with swagger2openapi.
• operationId collisions. Two operations with one id fail at manifest construction with ManifestError::DuplicateToolName (crates/platform/chio-manifest/src/validation.rs:50-56, reached from chio-openapi-mcp-bridge/src/lib.rs:199).
• Path parameters. A parameter that resolves to an empty string or a dot segment is rejected at invoke time, before dispatch.
• Redirects. A 3xx from the dispatcher is always an error; return it as-is and let the bridge reject it.
• Upstream credentials. Your dispatcher attaches Authorization headers or signs requests. The operator holds those credentials and decides how a client receives authority to use them.