Create your MCP server

The main MCP Stack creation path is Generate from OpenAPI. It turns an OpenAPI specification into a hosted MCP runtime and saves the server configuration to your organization.

Use the dashboard wizard when you want the server to be managed by MCP Stack, attached to Gateway, published through Host, and used by an agent. Use the CLI for the same hosted lifecycle from a terminal.

Before you start#

Have these ready:

• an OpenAPI 3.0 or 3.1 spec
• a public spec URL for the dashboard wizard
• a short server name you want to use in MCP Stack
• the upstream API base URL
• your target auth model: Public API, Static Headers, or Gateway

Publish lifecycle#

After you create or save a generated OpenAPI server, Host publishes automatically. Verify with tools/list before connecting clients or agents.

Saved changes to OpenAPI, enabled tools, runtime auth, environment variables, or Gateway configuration trigger the same publish path automatically.

Create it in the dashboard#

This is the best path if you plan to publish through Host, attach Gateway, or use MCP Stack agents.

The dashboard wizard starts by importing a public OpenAPI URL. From there, MCP Stack parses endpoints, security schemes, and server metadata before you choose tools and auth.

1. Sign in to MCP Stack.
2. Open MCP Servers.
3. Click Create Server.
4. Choose Generate from OpenAPI.

Step 1: Import API#

On the Import API step:

1. Paste your OpenAPI Specification URL.
2. Optionally enter a Server Name.
3. Click Continue.

Good to know:

• If you leave Server Name blank, MCP Stack generates it from the API title.
• The wizard includes example specs like Petstore and Stripe if you want to test the flow first.
• In the web wizard, the import step is URL-based. If your spec only exists as a local file, use the CLI option below.

Step 2: Select tools#

After MCP Stack analyzes the spec, it moves to Select Tools.

Use this step to decide what the agent should actually have access to:

1. Review the parsed endpoints grouped by tag.
2. Use Search endpoints... if the API is large.
3. Deselect any endpoint you do not want exposed as an MCP tool.
4. Expand important endpoints and add AI Instructions where needed.

The endpoint editor lets you add:

• Custom instructions for AI
• When to use
• When NOT to use

This is where you should trim noisy internal endpoints and make important tools easier for the model to use correctly.

Good tool instructions answer practical questions:

• What real-world task does this endpoint complete?
• What user wording should map to this tool?
• What information should the agent ask for first?
• What should the agent confirm before calling it?
• When is this tool the wrong choice?

Step 3: Configure runtime auth#

In the Authentication step, choose how the generated runtime should reach the upstream API:

• Public API: no credentials are injected.
• Static Headers: inject fixed headers like X-API-Key, X-Tenant-Id, or Authorization.
• Use MCP Stack Gateway: Gateway becomes the OAuth edge in front of the server.

If your OpenAPI spec declares security schemes, MCP Stack shows an auto-detection notice and recommends a mode. OAuth, OIDC, and HTTP bearer schemes should usually use Gateway because they represent user-scoped or bearer-protected access.

If the server uses user-scoped data, choose Gateway. The wizard can attach an existing reusable Gateway profile or create one inline from the OAuth inputs.

Step 4: Add AI prompts#

In AI Prompts, you can optionally add reusable context for the model.

Built-in templates include:

• Domain Context
• Response Format
• Error Handling

These are optional, but they are useful if you want the agent to speak in your product's language or follow a specific response style.

Use prompts for stable product context. Use tool instructions for endpoint-specific behavior.

Step 5: Review and create#

On Review:

1. Check the server name, API base URL, enabled tools, auth type, and prompts.
2. Click Create MCP Server.

When you create it in the dashboard, MCP Stack:

• saves the server configuration to your account
• enables usage analytics for the generated server
• redirects you to the Hosting tab on the new server's detail page
• starts publishing the hosted runtime automatically

From the detail page you can:

• attach or edit Gateway
• run tools/list smoke tests
• view publish logs and request logs
• enable, disable, and tune tools
• upload a newer OpenAPI spec with Add OpenAPI Spec or Update OpenAPI Spec

CLI path#

Use the CLI when you prefer creating and publishing from a terminal, wiring MCP Stack into CI, or inspecting a server after creation.

Install:

npm install -g @mcpstack/cli
mcpstack auth login

Create from a public OpenAPI URL:

mcpstack servers create \
  --name support-api \
  --slug support-api \
  --runtime-type hosted \
  --openapi-url https://api.example.com/openapi.json \
  --json

Create from a local OpenAPI file:

mcpstack servers create --openapi-file ./openapi.yaml --json

Replace the source spec later from the same local file path:

mcpstack servers update <server-id> --openapi-file ./openapi.yaml --json

Inspect and verify after publish:

mcpstack servers get support-api --json
mcpstack tools list support-api --json
mcpstack servers auth-config get support-api --json
mcpstack logs stream support-api
mcpstack smoke tools-list support-api --json

Watch a long-running publish:

mcpstack operations list support-api --json
mcpstack operations get support-api <operation-id> --json

API path#

Use the REST API when you want to create hosted servers from your own admin workflow or provisioning system.

Create the server:

POST /api/v1/organizations/{orgId}/mcp-servers
Authorization: Bearer {token}
Content-Type: application/json
 
{
  "name": "Support API",
  "slug": "support-api",
  "runtimeType": "hosted",
  "openApiSpecUrl": "https://api.example.com/openapi.json"
}

Update configuration after creation:

PATCH /api/v1/organizations/{orgId}/mcp-servers/{serverId}
Authorization: Bearer {token}
Content-Type: application/json
 
{
  "name": "Support API"
}

Replace a private OpenAPI spec without putting it on the public internet:

PATCH /api/v1/organizations/{orgId}/mcp-servers/{serverId}
Authorization: Bearer {token}
Content-Type: application/json
 
{
  "openApiSpecJson": "{ \"openapi\": \"3.1.0\", \"info\": { \"title\": \"Support API\", \"version\": \"1.0.0\" }, \"paths\": {} }",
  "openApiSpecSource": "upload",
  "openApiSpecFileName": "openapi.yaml"
}

Run hosted checks and smoke tests:

POST /api/v1/organizations/{orgId}/mcp-servers/{serverId}/hosting-checks
POST /api/v1/organizations/{orgId}/mcp-servers/{serverId}/mcp-smoke/tools-list

Read publish logs and deployment state:

GET /api/v1/organizations/{orgId}/mcp-servers/{serverId}/deployment
GET /api/v1/organizations/{orgId}/mcp-servers/{serverId}/logs?page=1&pageSize=50
GET /api/v1/organizations/{orgId}/mcp-servers/{serverId}/deployment-operations

The API response includes the server record. Hosted publishing starts automatically for generated OpenAPI servers the same way it does from the dashboard and CLI.

Troubleshooting#

Add a custom domain#

After the hosted server is healthy, you can attach a customer-owned subdomain from the dashboard, CLI, or API.

See Set up a custom MCP domain for the full workflow, DNS records, status stages, CLI commands, API endpoints, and troubleshooting. Use a subdomain only, such as mcp.example.com. The canonical MCP Stack URL remains available, and the custom /mcp URL becomes preferred only after DNS, managed TLS, and routing are active.

If the server will use OAuth#

For OAuth-protected APIs, generated servers should opt into MCP Stack Gateway:

• Gateway adds the OAuth flow and discovery edge in front of the hosted server
• your Gateway profile stores the downstream OAuth client registration
• MCP Stack stores the downstream grant server-side

Do not model user OAuth as a static Authorization header or bearer-token passthrough. Static headers are for fixed secrets. User OAuth belongs in Gateway.

mcpstack servers create \
  --name support-api \
  --openapi-url https://api.example.com/openapi.json

Recommended next steps#

Once the server exists:

1. Open the server detail page.
2. Watch the automatic Host publish on the Hosting tab.
3. Open Gateway if the server is OAuth-backed.
4. Open Connect and copy the MCP URL or client config.
5. Run a tools/list smoke test.
6. Attach the server to an agent.
7. Test one read-only prompt and one guarded write prompt before sharing it with users.