Stainless (API MCP server architecture)
Type: full-code · Vendor: Stainless Software, Inc. · Language: TypeScript · License: proprietary · Status: active · Status in practice: emerging · First released: 2024-01-01
Stainless generates and prescribes an architecture for MCP servers that turn an existing REST or OpenAPI surface into tools an agent can call.
Description. Stainless generates MCP servers from an API specification and publishes guidance on how to structure the resulting tool surface. The architecture guide describes several tool-exposure strategies, from mapping every endpoint one-to-one to a tool, to composite tools that bundle several API calls, to dynamic meta-tools that let the model discover endpoints on demand. The guidance also covers filtering which tools are exposed based on the user's permissions or OAuth scopes. Stainless targets API providers that want their service to be callable by agents.
Agent loop shape. An agent connects to a Stainless-generated MCP server that fronts an existing API. The server presents the API as tools, either one tool per endpoint, composite tools that run a sequence of calls, or dynamic meta-tools the model uses to discover and invoke endpoints on demand. The agent selects a tool, the server executes the underlying API call or sequence of calls, and the result returns to the agent's context for the next step.
Primary use cases
- generating MCP servers from an existing API
- exposing API endpoints as agent-callable tools
- bundling multi-step API workflows into single composite tools
- scoping the exposed tool set to user permissions
Key concepts
- Meta-tools (list/get/invoke endpoint) → tool-discovery (docs) — A trio of dynamic tools — list_api_endpoints, get_api_endpoint_schema, invoke_api_endpoint — that let the model browse and call API endpoints on demand instead of being handed one tool per endpoint.
- Composite tools → composite-service-mcp (docs) — Hand-designed higher-level tools that each run a fixed sequence of underlying API calls, so the agent invokes one task-level operation instead of orchestrating several endpoints itself.
- OpenAPI-driven generation → mcp (docs) — The Stainless build step that derives the MCP server, and its tool surface, from the same OpenAPI specification the provider already uses to generate SDKs.
- Scope-based tool filtering → direct-api-wrapper (docs) — Logic in the server's authentication flow that trims the advertised tool list to what the user's permissions or OAuth scopes allow.
Patterns this full-code implements —
- ★★Model Context Protocol
Stainless generates the MCP server itself from the provider's existing OpenAPI specification, so a service that already publishes an OpenAPI surface for its SDKs becomes callable over MCP by any conf…
- ★Direct API Wrapper
The default and recommended starting strategy maps every API endpoint one-to-one to a tool, exposing a stable API as agent-callable with minimal wrapper logic; the guide also documents filtering the…
- ★Composite Service
Stainless's MCP architecture guidance prescribes composite tools that perform a sequence of API calls as a single higher-level tool for multi-step workflows.
- ★Tool Discovery
Rather than exposing every endpoint as a static tool, the guide prescribes three meta-tools — list_api_endpoints, get_api_endpoint_schema, invoke_api_endpoint — so the model discovers, inspects, and…
Neighbourhood
Click any neighbour to follow the lineage. Scroll to zoom, drag to pan.
Alternatives & relatives
Listed as alternative by (3)
References
Provenance
- Last analyzed:
- Last updated:
- Verification status: partial