Contents

Docs / Start here

Quickstart: from a spec to a live server

Turn an OpenAPI spec into a server claude.ai can call, in about ten minutes and with no AI involved.

You'll use Swagger's public Petstore spec, so you can follow along without an API of your own. Nothing here needs an agent or any AI.

Before you start

You need Node 22 or later, and a GitHub or Google account to sign in with.

Install the CLI

npm i -g @abyssinia-labs/sokie

This installs the sokie command, and sok as a short alias. Every command takes --help, and --json when a script reads its output.

Sign in

sokie login

Your browser opens Sokie and asks whether to sign in the CLI on this computer. Choose Allow, and the terminal confirms it:

$ sokie login
Opening your browser to sign in. If it doesn't open, go to:
  https://sokie.sh/oauth/authorize?…
Signed in to https://sokie.sh as you@example.com.

New to Sokie? The same page makes your account. On a machine you reach over SSH, run sokie login --no-browser and follow its prompts.

Make a server from a spec

sokie init reads an OpenAPI 3 or Swagger 2 spec, from a file or a URL, and writes a server into a new directory:

$ sokie init https://petstore3.swagger.io/api/v3/openapi.json petstore --name Petstore
Created Petstore in petstore:
  sokie.json
  openapi.json (from https://petstore3.swagger.io/api/v3/openapi.json)
  tools/  19 files
  .gitignore  added .sokie/, where sokie dev keeps local secrets

! tools/addPet.md  No `risk`; write (the operation's floor) applies until you set one.  [unclassified-risk]
! tools/getPetById.md  `getPetById`'s description is 4 words. Agents choose tools by their descriptions: say what it returns and when to use it, in at least ten words.  [description-thin]
…
Next: read each tool's description and set its risk, then run sokie dev.

That's the whole server: sokie.json says what it is and how to reach the API, openapi.json is a copy of the spec, and each file in tools/ is one tool an agent can call, with its description as the file's body. There's no generated code to maintain. What a server is made of goes through each file.

The lines that start with ! are warnings. They point at things agents trip over, like a description that only repeats the tool's name, and they never stop a deploy. Leave them for now; Make tools easy for agents to use is how you clear them.

Or start in the app

New server in the app does the same from a browser. Paste a spec (or drop the file), give its URL, or pick one from a GitHub repository you've already linked to a server. Sokie says what it found, including OpenAPI 3, Swagger 2 or a GraphQL schema, and you can correct it. Then it shows every tool the spec becomes: leave tools out, and fix a thin description or an effect before anything is made. Name the server, choose private or public, and Create server and deploy.

Its files are the ones sokie init writes, with your changes. They stay on Sokie until you want them: Download files on the server's Tools tab gives you the folder to push, and sokie link (or Link a GitHub repository when you create it) makes that repository the source from then on.

Try it on your machine

The Petstore spec asks for an API key, so init set the server up for each person who connects to bring their own. The demo accepts any key, and its docs use special-key. Locally, the key goes in .sokie/dev.env, which init already kept out of git:

cd petstore
mkdir -p .sokie
echo "SOKIE_CALLER_KEY=special-key" > .sokie/dev.env

Then run the server on the same runtime a deploy uses:

$ sokie dev
! tools/addPet.md  No `risk`; write (the operation's floor) applies until you set one.  [unclassified-risk]
…
✓ Running Petstore: 19 tools, private (1154ms)

  Server     http://127.0.0.1:8787/mcp
  Inspector  http://127.0.0.1:8788
  Token      Bearer eyJhbGciOi…

  Watching for edits. Ctrl+C stops.

The inspector opens in your browser. Choose getPetById, enter 1 for petId, and choose Call tool to see the pet the API returns. To use a real MCP client instead, point it at the Server address and send the token as an Authorization header. The server is private, so every call needs it.

sokie dev reloads on every save. Change a tool's description and the inspector shows the new one at once. If an edit breaks the build, the last good build keeps serving until you fix it.

Deploy

Stop sokie dev with Ctrl+C, then:

$ sokie deploy --create
Deploying Petstore (19 tools) to majestic-lobster-123…
  building
  live
Live: https://majestic-lobster-123.sokie.cloud/mcp

Your server's name will differ. Sokie picks it at random, and it stays the same for good, so the address is safe to share. The server is private: only MCP clients you approve can call it.

--create is only for the first deploy. It links this directory to the new server, so from now on sokie deploy is enough.

Connect claude.ai

  1. In claude.ai, open Settings, then Connectors, and add a custom connector with your server's address.
  2. claude.ai sends you to Sokie, which asks whether to connect it to your server. Choose Allow.
  3. Ask Claude to look up pet 1 in the Petstore.

The first call needs your Petstore key, so Claude shows you a link to Sokie. The page asks you to Add your key for Petstore. Paste special-key, choose Save key, and ask Claude again. Sokie keeps the key encrypted and sends it only on your own calls.

That's a live server, built from a spec, that claude.ai calls as you.

Where to go next