Skip to main content

​
Prerequisites

  • Python 3.11+ installed on your machine
  • An OpenAPI specification for the API you want to wrap (JSON or YAML)
Don’t have a specification handy? Try one of these:
Looking for more APIs? The APIs.guru OpenAPI Directory maintains thousands of validated OpenAPI specifications from real-world APIs.

​
Step 1: Generate your server

1

Open the dashboard

Go to mcpblacksmith.com/dashboard and create a new project.
2

Upload your specification

Drag and drop your OpenAPI specification file (JSON or YAML) into the upload zone. MCP Blacksmith supports OpenAPI 2.0 (Swagger), 3.0, 3.1, and 3.2.
3

Configure

Optionally enable the Metadata Filter (free) to remove read-only and server-generated fields, or paid enhancement passes to optimize tool descriptions, parameters, and constraints for AI consumption. See Enhancement Passes for details.
4

Generate

Click Generate. MCP Blacksmith analyzes your specification, extracts all operations, builds typed models, configures authentication, and generates the complete server code.
5

Download

Download the generated server as a ZIP file. Extract it to a directory of your choice.

​
Step 2: Install dependencies

cd my-api-server
pip install -r requirements.txt

​
Step 3: Configure credentials

If your API requires authentication, open the .env file and fill in your credentials:
.env
# Example: API Key authentication
API_KEY=your-api-key-here

# Example: Bearer token
BEARER_TOKEN=your-token-here

# Example: OAuth2
OAUTH2_CLIENT_ID=your-client-id
OAUTH2_CLIENT_SECRET=your-client-secret
The .env file is pre-configured with the correct variable names for your API’s authentication scheme. You only need to configure the credentials for the tools you intend to use. If a tool requires credentials that are not provided, a warning is logged and the request will likely be rejected by the upstream API — unless the endpoint is public and does not require authentication. See Authentication for details on each authentication type.

​
Step 4: Run the server

python server.py
By default, the server starts with stdio transport — the standard for local MCP connections. You’ll see output like: 
INFO: MCP server 'The Cat API' started (transport: stdio)

​
Step 5: Connect to an MCP client

Add your server to your MCP client’s configuration. Most clients use a JSON configuration file: 
{
  "mcpServers": {
    "the-cat-api": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}
Restart your MCP client so the new configuration is picked up. Your API tools are now available to the AI agent.
See the full guide at Connecting to AI Agents for transport options, virtual environments, and troubleshooting.

​
What’s next?

Server structure

Understand what each generated file does.

Authentication

Configure OAuth2, API keys, JWT, and more.

Security features

Circuit breakers, rate limiting, and retries.

Enhancement passes

Optimize your server with free and AI-driven passes.