Getting Started

Create your MCP server

Import your OpenAPI spec, choose the right tools, configure authentication, and create a server you can run locally or manage in Emcy.

6 sections2 locales

Emcy gives you three good ways to create an MCP server:

  • Dashboard wizard if you want Emcy to save the configuration, download the generated code, and keep the server ready for agents later
  • Public wizard if you want to try the flow before signing up
  • CLI if your spec is local on disk or you want to stay fully code-first

Before you start#

Have these ready:

  • an OpenAPI 3.0 or 3.1 spec
  • a public spec URL if you are using the web wizard
  • a local file path if you are using the CLI
  • a short server name you want to use in Emcy
  • your target auth model if the server will be protected

If you are following the standards-first OAuth path, the reference example is the Todo sample app.

Option 1: Create it in the dashboard#

This is the best path if you plan to use the server with Emcy agents or the agent SDK.

  1. Sign in to Emcy.
  2. Open MCP Servers.
  3. Click Create Server, or go directly to /mcp-servers/new.

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, Emcy 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 Emcy 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 your most important tools easier for the agent to use correctly.

Step 3: Configure authentication#

In the Authentication step, choose how MCP clients should authenticate:

  • No Authentication
  • API Key (custom header and optional prefix — use Authorization with prefix Bearer for static bearer-style tokens)
  • OAuth 2.0

If your OpenAPI spec already declares security schemes, Emcy will show an Auto-detected security schemes notice and prefill what it can. Specs that only declare HTTP bearer are steered toward OAuth 2.0 for MCP client auth.

If the server will use user-scoped data, choose OAuth 2.0 here. The wizard will let you attach an existing Gateway or create a new Gateway inline. After creation, use the server Gateway tab to manage the public MCP URL, resource metadata, and downstream auth profile.

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.

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, Emcy:

  • saves the server configuration to your account
  • enables telemetry for the generated server
  • downloads a ZIP of the ready-to-run project
  • redirects you to the new server's detail page

From the detail page you can later:

  • update authentication
  • re-enable or disable endpoints
  • set the runtime Server URL
  • upload a newer OpenAPI spec with Add OpenAPI Spec or Update OpenAPI Spec

Option 2: Use the public wizard first#

If you are not signed in yet:

  1. Open the public Wizard flow from the marketing site.
  2. Walk through the same steps: Import, Select Tools, Authentication, AI Prompts, Review.
  3. On the final step, click Sign Up & Deploy.

This is useful if you want to validate the spec and tool list before creating an account.

Option 3: Use the CLI#

Use the CLI when:

  • your OpenAPI spec is a local file
  • you want a local project immediately
  • you prefer generating code outside the dashboard

Install or run it with npx:

BASH
npm install -g @emcy/openapi-to-mcp

Generate from a public URL:

BASH
npx @emcy/openapi-to-mcp generate --url https://api.example.com/openapi.json

Generate from a local file:

BASH
npx @emcy/openapi-to-mcp generate ./openapi.yaml

Then move into the generated project and run it:

BASH
cd my-api-mcp
npm install
npm run build
npm start

Choose the CLI if you want full control. Choose the dashboard wizard if you also want Host, Gateway, observability, and agent setup.

If the generated server will use OAuth#

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

  • Emcy Gateway owns the public MCP URL and OAuth flow
  • your Gateway profile stores the downstream OAuth client registration
  • Emcy stores the downstream grant server-side

Do not configure passthrough env vars on generated servers. OAuth now belongs on the Gateway side of the architecture.

Once the server exists, the next thing to do is usually one of these: