Instant OpenAPI Import: From Spec to MCP Server in 60 Seconds

If you've ever integrated an API with an AI assistant, you know the pain: reading documentation, writing wrapper code, handling authentication, parsing responses, and dealing with edge cases. What if you could skip all of that?

With Emcy's OpenAPI Import feature, you can go from an API specification to a working MCP server in under 60 seconds. No coding required.

The Traditional Approach

Traditionally, connecting an API to an AI assistant like Claude or ChatGPT requires:

1. Reading API documentation - Understanding endpoints, parameters, and response formats
2. Writing wrapper code - Creating functions that call the API correctly
3. Handling authentication - Managing API keys, OAuth tokens, or other auth methods
4. Parsing responses - Converting API responses to formats the AI can understand
5. Error handling - Gracefully managing failures and edge cases
6. Maintenance - Updating your code when the API changes

This process typically takes hours or days, depending on the API complexity.

The Emcy Way

With Emcy, the process is radically simpler:

1. Paste your OpenAPI URL - We fetch and parse your spec automatically
2. Select endpoints - Choose which operations to expose as MCP tools
3. Configure auth - Set up authentication with a few clicks
4. Download & run - Get a complete MCP server project

That's it. No coding, no debugging, no maintenance headaches.

How It Works

Step 1: Provide Your OpenAPI Specification

Emcy accepts OpenAPI 3.0 and 3.1 specifications in JSON or YAML format. You can:

• Paste a URL - We'll fetch and validate the spec for you
• Upload a file - Drop your spec file directly into the wizard
• Paste raw content - Copy and paste the spec content

# Example: Using a public API spec
https://api.example.com/openapi.json

Step 2: Select Your Endpoints

Once we parse your spec, you'll see a list of all available operations. Each endpoint shows:

• Operation name - The function name that will be exposed to AI
• HTTP method - GET, POST, PUT, DELETE, etc.
• Description - What the endpoint does
• Parameters - Required and optional inputs

Select the endpoints you want to expose. You can always add more later.

Step 3: Configure Authentication

Emcy supports multiple authentication patterns:

Static API Key

// Your API key is injected at runtime
headers: {
  "Authorization": `Bearer ${process.env.API_KEY}`
}

Passthrough Headers

// Headers are passed through from the MCP client
headers: {
  "Authorization": request.headers.authorization
}

No Authentication

// For public APIs that don't require auth
headers: {
  "Content-Type": "application/json"
}

Step 4: Download and Run

Click "Generate" and you'll receive a complete Node.js project:

my-mcp-server/
├── src/
│   ├── index.ts      # MCP server entry point
│   └── transport.ts  # Stdio/HTTP transport config
├── package.json      # Dependencies and scripts
├── tsconfig.json     # TypeScript configuration
├── .env.example      # Environment variables template
└── README.md         # Setup instructions

Running it is simple:

cd my-mcp-server
npm install
npm run build
npm start

Real-World Example: GitHub API

Let's walk through a concrete example using the GitHub API.

1. Start with the OpenAPI Spec

GitHub publishes their OpenAPI specification at:

https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json

2. Select Key Endpoints

For a typical workflow, you might select:

• GET /repos/{owner}/{repo} - Get repository info
• GET /repos/{owner}/{repo}/issues - List issues
• POST /repos/{owner}/{repo}/issues - Create issue
• GET /repos/{owner}/{repo}/pulls - List pull requests

3. Configure GitHub Token

Set up authentication with a personal access token:

API_KEY=ghp_xxxxxxxxxxxxxxxxxxxx

4. Connect to Claude

Add to your Claude Desktop config:

{
  "mcpServers": {
    "github": {
      "command": "node",
      "args": ["/path/to/github-mcp/dist/index.js"],
      "env": {
        "API_KEY": "ghp_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Now Claude can interact with GitHub directly!

What Gets Generated

The generated MCP server includes:

Tool Definitions

Each endpoint becomes an MCP tool with proper typing:

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "get_repository",
      description: "Get information about a repository",
      inputSchema: {
        type: "object",
        properties: {
          owner: { type: "string", description: "Repository owner" },
          repo: { type: "string", description: "Repository name" },
        },
        required: ["owner", "repo"],
      },
    },
    // ... more tools
  ],
}));

Request Handlers

Each tool has a corresponding handler that calls the actual API:

case "get_repository": {
  const { owner, repo } = args;
  const response = await fetch(
    `https://api.github.com/repos/${owner}/${repo}`,
    { headers }
  );
  return { content: [{ type: "text", text: JSON.stringify(await response.json()) }] };
}

Error Handling

Robust error handling is included by default:

if (!response.ok) {
  return {
    content: [{
      type: "text",
      text: JSON.stringify({
        error: true,
        status: response.status,
        message: await response.text(),
      }),
    }],
    isError: true,
  };
}

Advanced Features

Custom Tool Names

By default, tool names are generated from operation IDs. You can customize them:

// Default: repos_owner_repo_get
// Custom: get_repository

Response Transformation

Add post-processing to simplify responses for AI consumption:

const response = await fetch(url, options);
const data = await response.json();

// Extract only what the AI needs
return {
  name: data.name,
  description: data.description,
  stars: data.stargazers_count,
  issues: data.open_issues_count,
};

Telemetry Integration

Track usage with our SDK:

import { EmcyTelemetry } from "@emcy/sdk";

const telemetry = new EmcyTelemetry({
  apiKey: process.env.EMCY_API_KEY,
  serverName: "github",
});

// Wrap each tool call
const result = await telemetry.trace("get_repository", async () => {
  return await fetchRepository(owner, repo);
});

Benefits of the Emcy Approach

Speed

What takes days manually takes 60 seconds with Emcy. Import, configure, download, run.

Consistency

Every generated server follows best practices for error handling, logging, and transport configuration.

Maintainability

When the API changes, regenerate your server from the updated spec. No manual code updates needed.

Observability

Add telemetry with one flag to track every tool call, monitor performance, and debug issues.

Getting Started

Ready to try it yourself?

1. Sign up at emcy.ai/signup
2. Click "New MCP Server" in your dashboard
3. Paste your OpenAPI URL and follow the wizard
4. Download and run your generated server

The entire process takes less than a minute. Your AI assistants will thank you.

---

Have an API you'd like to connect? Start your free trial and generate your first MCP server today.