MCP server for agents

AI agents can use your APIs the way readers do. rapidoc build turns every local spec and every workflow into MCP tool manifests, and rapidoc serve hosts them at /mcp: one endpoint for the whole portal, with the same access rules as the pages.

dist/mcp/<api id>.json              the API's operations as tools, named <api id>_<operation>
dist/mcp/workflows/<id>.json        each workflow of the file as one tool, its inputs as the arguments

Nothing to configure: a build has the manifests whenever it has specs on disk (a spec that is a URL is left out).

With rapidoc serve, the portal’s MCP endpoint is https://<your portal>/mcp (Streamable HTTP). A client that speaks stdio only, such as Claude Desktop, connects through mcp-remote:

{
  "mcpServers": {
    "acme-portal": {
      "command": "npx",
      "args": ["mcp-remote", "https://developers.acme.com/mcp"]
    }
  }
}

Without a token, the agent sees the public APIs and calls them without credentials.

On a portal with sign-in, a signed-in reader opens the user menu and picks Connect an AI agent. Get token mints a token for their agents and shows the command that uses it:

npx mcp-remote https://developers.acme.com/mcp --header "Authorization: Bearer <token>"

With the token, the agent:

• sees the tools of every API the reader may see, and the workflows whose APIs they may all see;
• with auth.tryIt, calls the APIs with the reader’s own access token, so the API’s permission check applies to the agent as it does to Try.

The token is the reader’s session (sealed like the cookies, never a copy of them) and lasts as long as the session. It opens exactly what the reader can see; a reader can’t give an agent more than they have.

The reader’s access token fills oauth2, openIdConnect and HTTP bearer schemes. For an API that takes an API key or HTTP Basic, set the credential in the environment of rapidoc serve, named like the exported project’s: the scheme id in upper snake case (PARTNER_KEY), <SCHEME>_USERNAME and <SCHEME>_PASSWORD for Basic, or API_KEY for any scheme. Every agent then calls that API with the same key.

For an API that isn’t in a portal, or to try its tools before building one, the CLI turns any spec into an MCP server:

npx rapidoc mcp export openapi.yaml --out-dir orders-mcp   # writes the server project
npx rapidoc mcp serve openapi.yaml                         # runs it over stdio, no files

mcp serve is what an agent’s config can run directly (it needs @modelcontextprotocol/sdk installed next to the CLI):

{
  "mcpServers": {
    "orders": { "command": "npx", "args": ["rapidoc", "mcp", "serve", "./specs/orders.yaml"] }
  }
}

Credentials come from the environment, one variable per security scheme as in the exported project (BEARER_AUTH for a scheme BearerAuth). --base-url http://localhost:4010/orders sends the calls to rapidoc mock instead of the spec’s server, and --arazzo flows.arazzo.yaml adds the workflows as tools.

Readers can also download a standalone MCP server for one API from its reference page (Export MCP server, with rapidoc.mcp: true): a small stdio server with the same manifest and runtime, for agents that run where the portal can’t be reached.