# OpenAPI MCP Server

A Cloudflare Workers-based service that dynamically creates an MCP server from any OpenAPI schema definition endpoint. This server enables seamless integration with tools like Prompteus, Claude, and Cursor.

This project is actively developed by the team at [Prompteus](https://prompteus.com).

## Quick Start

1. Install dependencies:
```bash
npm install
```

2. Run the service locally:
```bash
npm run dev
```

The service will be available at `http://localhost:8787`.

## Hosted Service

We provide a free, best-effort hosted version of this service at [bridge.openapitomcp.com](https://bridge.openapitomcp.com). This service is maintained by the Prompteus team and is available for public use. While we strive to maintain high availability, please note that this is provided as-is without any guarantees of uptime or support.

To use the hosted service, simply replace `http://localhost:8787` with `https://bridge.openapitomcp.com` in any of the examples below.

## How It Works

This service acts as a stateless proxy between MCP clients and OpenAPI-documented APIs. It requires basic endpoint configuration, which is passed as a base64url-encoded JSON object in the URL.

### Example: PetStore API Integration

Let's walk through connecting to Swagger's sample PetStore API:

- OpenAPI Schema: `https://petstore3.swagger.io/api/v3/openapi.json`
- API Base URL: `https://petstore3.swagger.io/api/v3`

1. Create the configuration payload:
```javascript
const payload = {
    schemaUrl: 'https://petstore3.swagger.io/api/v3/openapi.json',
    baseUrl: 'https://petstore3.swagger.io/api/v3'
};
```

2. Convert to base64url format:
```javascript
const base64Payload = btoa(JSON.stringify(payload))
    .replace(/=/g, '')
    .replace(/\+/g, '-')
    .replace(/\//g, '_');
```

3. Construct the MCP server URL:
```
http://localhost:8787/mcp/{base64Payload}
```

Once configured, you can use this MCP server to interact with the PetStore API through various tools. Available operations include:
- Listing pets
- Adding new pets
- Updating pet information
- Deleting pets
- And more...

The MCP server automatically handles the OpenAPI schema and provides a consistent interface for all API interactions.

### Using openapitomcp.com

For convenience, we provide a web interface at [openapitomcp.com](https://openapitomcp.com) that automatically generates the configuration payload for you.

## Tool-Specific Configuration

### Prompteus
Prompteus provides powerful workflow capabilities with MCP server integration. You can create complex workflows that leverage MCP servers through the Call AI Model node:

1. Navigate to the MCP Servers page in Prompteus
2. Click the **Import MCP Server** button
3. Enter the MCP server URL (e.g., `https://bridge.openapitomcp.com/mcp/{base64Payload}`)
4. Click **Fetch** to validate and initialize the server
5. Optionally add a **Friendly Name** to distinguish between multiple MCP servers
6. Select the desired **Tools** and **Resources** from the available options
7. Click **Import** to complete the setup

To use the MCP server in a Neuron workflow:
1. Add a Call AI Model node to your workflow
2. In the node's settings, select your MCP server from the dropdown
3. You can select multiple MCP servers for a single workflow
4. The selected tools and resources will be available for use in your workflow

### Cursor
1. Press `CTRL/CMD+Shift+J` to open Settings
2. Navigate to MCP settings
3. Select "Add new global MCP server"
4. Add this configuration:
```json
{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8787/mcp/{base64Payload}"]
    }
  }
}
```

### Visual Studio Code
1. Press `CTRL/CMD+P` and search for "MCP: Add Server"
2. Choose "Command (stdio)"
3. Enter this configuration:
```
npx mcp-remote http://localhost:8787/mcp/{base64Payload}
```
4. Name the server (e.g., "Linear")
5. Activate the server through "MCP: List Servers"

### Windsurf
1. Press `CTRL/CMD+,` to open settings
2. Navigate to "Cascade -> MCP servers"
3. Select "Add Server -> Add custom server"
4. Add this configuration:
```json
{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8787/mcp/{base64Payload}"]
    }
  }
}
```

### Zed
1. Press `CMD+,` to open settings
2. Add this configuration:
```json
{ 
  "context_servers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8787/mcp/{base64Payload}"]
    },
    "settings": {}
  }
}
```