Skip to main content
Once you have a bridge.mcp/v1 manifest — generated by bridge generate mcp or hand-edited — you serve it with either bridge mcp serve (stdio) or bridge mcp serve-http (HTTP). Both commands load the same manifest and expose the same tools. The difference is transport: stdio for local MCP clients that launch subprocesses, HTTP for remote or browser-based clients.

​
Before you begin

  • A bridge.mcp/v1 manifest file (Generate an MCP server)
  • Any environment variables referenced in the manifest set in your shell
  • For DB-backed manifests: bridge.yaml in the manifest’s directory with the named provider configured

​
Stdio

bridge mcp serve ./my-api.mcp.yaml
This starts a JSON-RPC 2.0 MCP server on stdin/stdout. The process runs until the MCP client closes the connection. This is the mode used by Claude Desktop, Cursor, and any other MCP host that launches the server as a subprocess. At startup, Bridge:
  1. reads and validates the manifest
  2. resolves environment variables referenced in the manifest
  3. for DB-backed manifests, locates bridge.yaml in the manifest’s directory and connects to the named provider
  4. begins serving tools/list and tools/call requests over stdin/stdout
If a required environment variable is missing or a DB connection fails, the server exits immediately with an error on stderr.

​
HTTP

bridge mcp serve-http ./my-api.mcp.yaml
This starts an HTTP server on 127.0.0.1:8080 by default. Startup follows the same steps as stdio: manifest validation, env var resolution, and provider connection happen before the server accepts any requests.

​
Endpoints

PathMethodPurpose
/mcpPOSTMCP endpoint (Streamable HTTP transport)
/healthzGETLiveness check — returns 200 when the server process is running
/readyzGETReadiness check — returns 200 when the server can handle MCP requests

​
Bind address

Change the address and port the server listens on: 
bridge mcp serve-http ./my-api.mcp.yaml --bind 0.0.0.0:9000
The --bind value can also be set with the BRIDGE_MCP_BIND environment variable.

​
Public URL

If you are running behind a proxy or exposing the server externally, set a public URL so it appears correctly in health output and startup logs: 
bridge mcp serve-http ./my-api.mcp.yaml \
  --bind 0.0.0.0:9000 \
  --public-url https://mcp.example.com
Bridge appends /mcp, /healthz, and /readyz to the public URL in its output.

​
CORS

Requests with no Origin header (non-browser clients) are always accepted. Browser-originated requests must have an Origin that is either a loopback address or one explicitly allowed: 
bridge mcp serve-http ./my-api.mcp.yaml \
  --allow-origin https://app.example.com
Repeat --allow-origin to allow multiple origins.

​
Request limits

FlagDefaultDescription
--max-header-bytes32768 (32 KB)Max HTTP header bytes per request
--max-body-bytes1048576 (1 MB)Max HTTP body bytes per request
--read-timeout-secs15Budget for reading a request off the wire
--request-timeout-secsglobal --timeoutBudget for handling a request after it is read
All of these can also be set via their corresponding BRIDGE_MCP_* environment variables.

​
Graceful shutdown

The server listens for SIGTERM and SIGINT. On receipt, it stops accepting new connections and waits up to --shutdown-grace-secs (default 10) for in-flight requests to complete before exiting. 
bridge mcp serve-http ./my-api.mcp.yaml --shutdown-grace-secs 30

​
Environment variables at runtime

Bridge resolves environment variables from the process environment when the server starts, not when the manifest was generated. For OpenAPI-backed manifests, set:
  • the variable named in --base-url-env — the API base URL
  • the variable named in --bearer-env — the bearer token, if auth is configured
For DB-backed manifests, Bridge reads the provider URI from bridge.yaml and expands any ${VAR_NAME} references in it. Bridge does not load .env files. Set variables in your shell, your process manager, or your deployment environment before starting the server.

​
Wire into an MCP client

​
Claude Desktop

The client_snippet in bridge generate mcp output is ready to paste directly. Open your Claude Desktop config — usually at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS — and add: 
{
  "mcpServers": {
    "my-api": {
      "command": "/usr/local/bin/bridge",
      "args": ["mcp", "serve", "/absolute/path/to/my-api.mcp.yaml"]
    }
  }
}
Restart Claude Desktop. The tools from your manifest appear in the tool list immediately.
Use the absolute manifest path in the args array. Claude Desktop launches the server from a different working directory, so relative paths will not resolve correctly.

​
Cursor

Add the same mcpServers block to your Cursor MCP settings. The command and args shape is identical.

​
Any HTTP MCP client

For clients that connect over HTTP rather than launching a subprocess, point them at the /mcp endpoint: 
http://127.0.0.1:8080/mcp
Or, if you configured a public URL: 
https://mcp.example.com/mcp

Generate an MCP server

Generate the manifest that this page serves.

MCP manifest

See the full bridge.mcp/v1 format and what each field controls.

Commands

Full flag reference for bridge mcp serve and bridge mcp serve-http.

Bridge, MCP, and A2A

Understand where Bridge-hosted MCP servers fit in the broader agent stack.