# OpenAPI to MCP server

> Turn an OpenAPI or Swagger spec into a hosted MCP server: what each operation, parameter, server and security scheme becomes.

Source: https://sokie.sh/docs/openapi-to-mcp-server

An MCP server lets an agent call your API through tools it can discover and describe to itself. If your API has an OpenAPI spec, you already have most of what that server needs: every operation, its parameters, its request body, where the API answers and how it signs in. Sokie reads the spec and serves those operations as typed tools on a live server, at `https://<slug>.sokie.cloud/mcp`. There's no code to generate or maintain, and no AI in the loop: the tools come from the spec, and you bring your own agent.

This page covers what happens to a spec on the way, part by part. To follow along with a real API, the [quickstart](https://sokie.sh/docs/quickstart) does the same steps with Swagger's Petstore.

## Four commands

Install the CLI with `npm i -g @abyssinia-labs/sokie` (Node 22 or later), then:

```sh
sokie init openapi.yaml billing
cd billing
sokie dev
sokie login
sokie deploy --create
```

- **`sokie init`** reads an OpenAPI 3 or Swagger 2 spec, from a file or a URL, and writes the server into a new directory: `sokie.json`, a copy of the spec, and one file per tool in `tools/`. It checks the result as it goes, and lists anything agents will trip over.
- **`sokie dev`** runs the server on your machine, on the same runtime a deploy uses, with an inspector to call each tool. It reloads on every save.
- **`sokie login`** signs the CLI in. `init` and `dev` work without it; deploying is the first thing that needs an account.
- **`sokie deploy --create`** makes the server and deploys it, then prints its address. From then on, `sokie deploy` is enough.

Prefer a browser? **New server** in the app takes the same spec, pasted, dropped or from a URL, shows every tool it becomes, and deploys it. And once the files are in a GitHub repository, [linking it](https://sokie.sh/docs/link-a-repository) deploys every push and gives every pull request a preview server of its own.

## What maps to what

| In the spec | On the MCP server |
| --- | --- |
| An operation | A tool, with a file of its own in `tools/` |
| `operationId` | The tool's name |
| `summary`, when it's short | The tool's title |
| `description`, or the summary when there's none | The tool's description, which agents read to choose it |
| Path, query, header and cookie parameters | Properties of the tool's input, with their schemas |
| The request body | One more input property, `body` |
| The HTTP method | The tool's risk: what a call can do |
| The first tag | The tool's area |
| `servers` | Where every call goes |
| `security` and its schemes | How the server signs in to your API |
| `deprecated: true` | A line in the description saying the operation may go away |
| `x-mcp: false` on an operation or a path | No tool |

### Operations become tools

Every operation in `paths` is a tool, named for its `operationId`. A name with characters a tool can't have is repaired: spaces and punctuation become `_`, and it's cut to 64 characters. An operation with no `operationId` is named for its method and path, so `GET /tasks/{taskId}/comments` becomes `getTasksByTaskIdComments`. Two names that would clash, even only in case, get a number.

Each tool is a short Markdown file. Its frontmatter names the operation, and its body is the description:

```md
---
operation: GET /tasks/{taskId}
title: Get a task
risk: read
---

Get one task by its id, with its title, status, due date and project.
```

A tool exists because its file does. Delete a file and that operation is no longer offered; `sokie check` lists the spec's operations without a tool, as a note, so none are left out by accident. To keep an operation out from the start, mark it `x-mcp: false` in the spec.

The first draft of each description is the spec's own, and specs are often terse: "Find pet by ID" doesn't tell an agent when to choose it. `sokie init` flags those as warnings. [Make tools easy for agents to use](https://sokie.sh/docs/improve-tools) is how to rewrite them, and they never stop a deploy.

### Parameters become the tool's input

A tool's input is a JSON Schema object with one property per parameter, taken from the parameter's own schema. Path parameters, and any parameter marked `required`, are required. A request body is one more property, `body`, required when the spec says it is. You never write the input by hand; it's built from the spec when the server is built, so it always matches the operation.

On each call, every argument goes where the spec says, written the way it says: path, query, header or cookie, following each parameter's `style` and `explode`. Request bodies can be JSON, a form, `multipart/form-data`, text such as XML, or a file, which the agent sends in base64 ([Sending files](https://sokie.sh/docs/what-is-a-server#sending-files)). [What a call sends](https://sokie.sh/docs/what-is-a-server#what-a-call-sends) has every rule.

`$ref`s inside the spec resolve, cycles included: a schema that contains itself is cut where it repeats. A `$ref` to another file doesn't, because a server's build reads only its own copy of the spec. Bundle the spec into one file first.

### Methods become risk

Each tool has a risk: `read`, `write`, `delete` or `external_effect`, for a call that acts outside the API, like sending an email. Sokie tells clients whether a tool only reads, or can delete or act outside the API, and many clients use that to decide when to ask before calling.

Until you set one, a tool takes its method's floor: `GET`, `HEAD`, `OPTIONS` and `QUERY` are reads, `DELETE` is a delete, and any other method, like `POST`, `PUT` or `PATCH`, is a write. You can raise a tool above its floor but never lower it, so a `POST` that only searches stays a write. `sokie init` sets `risk: read` where the method makes it certain, and leaves the rest for you to decide.

### Servers become where calls go

Every call goes to the spec's first server URL, with its `{variables}` filled in from their defaults. A relative URL, like Petstore's `/api/v3`, is read against where the spec came from. With no top-level `servers`, the first one a path or an operation declares is used.

If the spec names no server, or a relative one read from a file, or one with a variable that has no default, give the address with `sokie init <spec> --base-url https://api.example.com`. The address you give lands in `sokie.json` as `upstream.baseUrl`, which wins over the spec's own server, so you can change where calls go without touching the spec.

### Security schemes become sign-in

What a spec says about signing in decides how the server sends credentials to your API:

- **An API key**, in a header, the query or a cookie, **or a bearer token** becomes a key each person who connects brings for themselves. The first call that needs it shows them a link to add it, and Sokie sends it only on their own calls.
- **HTTP Basic** works the same way, with each person entering `username:password`.
- **OAuth 2 or OpenID Connect** needs an OAuth app of your own, and the authorization code flow. The **New server** page starts the sign-in from the spec's addresses and scopes, and `sokie init` says what to add to `sokie.json`. Each person can sign in to your API, or one sign-in can serve everyone.
- **OAuth's client credentials**, when it's the spec's only OAuth flow, has the server sign in as itself, with an API client of yours: `sokie init` sets it up and says which two secrets to set, the client id and secret.
- **No security schemes** means the server sends no credentials, unless you say otherwise.

When the spec lists several schemes, Sokie takes the ones it applies with `security`, or every scheme it defines when it applies none, and among them prefers one it can send: a key or a bearer token first, then Basic or a cookie, then OAuth people sign in with, then client credentials. `--auth` overrides the spec, for example `--auth bearer` or `--auth header:X-Api-Key`, and one key shared by every caller is a secret you set once. [How clients sign in](https://sokie.sh/docs/how-clients-sign-in#your-apis-credentials) covers every choice. Calls into the server itself are separate: a private server signs MCP clients in with OAuth, so nobody copies a token.

## Large APIs

Past 40 tools, `sokie init` sets `"discovery": "search"`. Clients then see three tools, one to search the rest, one to read a tool's definition and one to call it, so a large API doesn't fill an agent's context before it starts. The spec can be up to 14 MiB as JSON, and 2 MiB as YAML; GitHub's REST spec, with more than 1,200 operations, deploys as one server.

## OpenAPI 3.0, 3.1 and 3.2

Sokie reads every OpenAPI 3 version. From 3.2 it also takes `QUERY` operations and the methods under `additionalOperations` that a request can carry, a whole query string given as one parameter (`in: querystring`), `itemSchema` for answers that stream, and `$self` for resolving references. An operation whose answers are JSON Lines, JSON Text Sequences or server-sent events becomes a tool that collects the stream and returns its items as one list.

## Swagger 2

A Swagger 2 spec works as it is, with no conversion step:

- **Where calls go** is `schemes`, `host` and `basePath` together: `https://api.example.com/v1`. With no `schemes`, it's `https`. With no `host`, give `--base-url`.
- **Parameters** carry their schema keywords on themselves, as Swagger 2 writes them, and arrays follow their `collectionFormat`: `csv` when there's none, or `multi`, `ssv`, `tsv` and `pipes`. That holds for `formData` fields too.
- **A `body` parameter** is the tool's `body`, and `formData` parameters are fields of a form or `multipart/form-data` body. A `file` field is a file part, and a `body` whose `consumes` are all file types, such as `application/octet-stream`, is a file.
- **Sign-in** comes from `securityDefinitions`. An `apiKey` scheme becomes each caller's key. For a `basic` scheme, give `--auth basic`, and each caller enters `username:password`. An `oauth2` scheme with the `accessCode` flow is the authorization code flow above, and one with the `application` flow is client credentials.

## GraphQL

A GraphQL schema becomes a server too, with `sokie init schema.graphql --base-url https://api.example.com/graphql --auth bearer`. Every field on `Query` and `Mutation` is a tool, its arguments are the input, and Sokie writes each tool's query document, so an agent never writes GraphQL. A schema says neither where its API answers nor how it signs in, which is why both flags are needed. [GraphQL APIs](https://sokie.sh/docs/graphql) covers what each tool asks for, and its limits.

## Where to go next

- [Quickstart](https://sokie.sh/docs/quickstart): the same steps on a real API, from install to a call from claude.ai.
- [Add an API to Claude](https://sokie.sh/docs/add-an-api-to-claude) or [to ChatGPT](https://sokie.sh/docs/add-an-api-to-chatgpt) as a connector.
- [What a server is made of](https://sokie.sh/docs/what-is-a-server): every field of `sokie.json` and a tool file.
- [Checks](https://sokie.sh/docs/checks): everything `sokie init` and `sokie check` look for.
- [How Sokie compares](https://sokie.sh/compare) with Speakeasy, Zuplo and FastMCP, and moving from Stainless.
