Start with the right path | MCP Stack Docs

MCP Stack helps developers turn existing APIs into production-ready MCP endpoints and agent experiences. The platform is easiest to understand as four layers:

Generate a TypeScript MCP runtime from an OpenAPI specification.
Gateway adds the OAuth edge in front of a server: OAuth discovery, user-scoped grant brokering, scopes, logs, and policy.
Host runs generated OpenAPI MCP runtimes for you with managed publishing, health, global routing, logs, and usage controls.
Agents and Embed put those MCP tools inside an assistant that can run in MCP Stack, external clients, or your own product.

MCP Stack product flow from OpenAPI to embedded agent

API teams usually start on the left with OpenAPI. OAuth-protected APIs move through Gateway. Hosted runtimes produce the public /mcp endpoint. Product teams attach the server to an agent and embed the assistant in their app.

The shortest successful path

If your API has an OpenAPI URL, create a generated MCP server first. Select a small set of useful tools, choose the runtime auth model, let Host publish it, then run the tools/list smoke test before adding it to an agent.

Which path should I choose?#

Use Generate from OpenAPI when your product already has an OpenAPI 3.0 or 3.1 spec and you want MCP Stack to create and host the MCP runtime. This is the primary self-service path.

MCP Stack create path chooser

The create screen starts with the two first-class paths: generate a new MCP runtime from OpenAPI, or move into the agent app flow after a server is ready.

Choose Use MCP Stack Gateway when the API is user-scoped or OAuth-backed and you want OAuth handled at the edge instead of handing client tokens directly to the runtime.

Use Static Headers when every upstream API call should include the same API key, tenant header, or static bearer value. This is not a per-user OAuth model.

Use Public API when the upstream API is open, test-only, or already protected behind a trusted network boundary and the MCP runtime does not need credentials.

Use Agents and Embed after at least one server exists. Agents combine MCP tools, model configuration, a system prompt, user/session context, and optional local clientTools.

Recommended first project#

Pick one low-risk API domain with clear user value. Good first servers expose 5 to 20 tools, not every endpoint in a large API.

Strong examples:

Customer support lookup, notes, and ticket updates.
Internal operations dashboards with read tools first.
CRM account search and next-action helpers.
Billing or invoice lookups with guarded write actions.

Avoid starting with:

Admin-only destructive actions.
Endpoints with unclear side effects.
APIs without reliable OAuth, resource, and scope boundaries.
Huge specs where every endpoint is exposed as a tool.

The build sequence#

Import an OpenAPI spec

Paste a public OpenAPI URL into the dashboard wizard. The parser extracts API title, base URL, security schemes, tags, operations, parameters, and request bodies.

Select tools intentionally

Keep the tools a developer or end user can explain. Disable noisy internal endpoints. Add "when to use" and "when not to use" instructions to important write operations.

Choose runtime auth

Pick Public API, Static Headers, or Gateway. For OAuth-protected or bearer-protected user data, Gateway is the right MCP Stack path.

Create the server

The dashboard saves the server config and starts Host publishing automatically. The Hosting tab shows progress and the production /mcp endpoint.

Connect an agent

Create an agent, attach the MCP server, choose a model, write a system prompt, and test the auth/connect flow before embedding it in your product.

What success looks like#

Your first MCP Stack implementation is ready when:

The generated server has only the tools you want the agent to call.
OAuth, resource, scopes, and callback settings are configured in Gateway if the upstream API is user-scoped.
The hosted MCP URL is public and ends in /mcp.
Optional customer-owned custom domains can replace the preferred MCP URL after DNS and TLS are active. See Set up a custom MCP domain.
Hosting is healthy in every enabled edge region.
tools/list passes from the dashboard or CLI.
A simple tool call succeeds from an agent or external MCP client.
The agent prompt explains who the agent helps, what tools it can use, and what it must confirm before changing data.

Quick answer#

Start from what you already have:

You have an OpenAPI spec: create a generated MCP server.
Your API is OAuth-backed or user-scoped: configure Gateway before publishing with Host.
You want an in-product assistant: build an agent and embed it after the server exists.
You want to use the server from Claude, ChatGPT, VS Code, or Cursor: connect an MCP client after publishing.