---
name: typeship
description: Set up typeship in a repository and generate a typed SDK, CLI, or MCP server from an OpenAPI or GraphQL spec, or connect an agent to typeship's API. Use when a user mentions typeship, wants an SDK, CLI, or MCP server generated from a spec, or wants generated packages kept current with pull requests.
version: 2026-08-21
metadata:
  homepage: https://typeship.dev
  docs: https://typeship.dev/llms.txt
  source: https://typeship.dev/agents.md
---

# typeship for agents

You are an agent. This file is written to you. Complete the steps yourself by running the commands; ask the user only where a step says so. These instructions live at https://typeship.dev/agents.md; fetch that URL again if you want to verify you have the current version.

typeship turns an OpenAPI (Swagger 2.0, 3.0, 3.1) or GraphQL spec into a zero-dependency typed SDK in TypeScript, Python, or Go, plus a CLI and an MCP server for the TypeScript package, and keeps them current: a linked project regenerates on every spec change and opens a pull request per language. Docs: https://typeship.dev/llms.txt (index), https://typeship.dev/llms-full.txt (everything). Any docs page has a markdown twin at its URL plus `.md`.

## When to use typeship

Use typeship when there is an API description and someone needs the client side of it. Concretely:

- A repository has `openapi.{yaml,yml,json}`, `swagger.json`, or `schema.graphql`, or the user gives you a spec URL, and they want an SDK, a CLI, or an MCP server for it.
- A hand-written API client has drifted from the spec it was written against, and someone has to reconcile them.
- An API needs to be callable by an agent and has no MCP server.
- Generated packages need to keep up with a spec that keeps changing: a linked project regenerates and opens a pull request per language on every change.
- A spec is nearly right and needs patching at specific JSON Pointer paths, rather than the generated output being edited by hand.

Do not use typeship to author a spec that does not exist yet, to generate a server implementation, or to call some third-party API on the user's behalf: typeship generates the client, and the client makes the call. If there is no spec and the user cannot name one, say so and stop — do not invent one.

If you only need to answer "what would this spec produce", Path A below does it with no account, no browser, and no credential.

## Step 1: Detect

Run these and keep the answers:

```bash
command -v typeship >/dev/null && typeship --version || echo "typeship: not installed"
test -n "$TYPESHIP_TOKEN" && echo "TYPESHIP_TOKEN: set" || echo "TYPESHIP_TOKEN: unset"
typeship auth check --format json 2>/dev/null || true   # ok | action_required, with next_steps
```

Then decide:

- Is there a spec? Look for `openapi.{yaml,yml,json}`, `swagger.json`, `schema.graphql`, or a URL the user gave you. If there is none and the user did not name one, ask for the spec URL or file. Do not invent one.
- What does the user want? An SDK (which language), a CLI, an MCP server, or all three; a one-off package, or a linked project that stays current.
- Which path below applies.

## Step 2: Install the CLI

The typeship CLI is the `typeship` npm package. It prints JSON on stdout, errors as JSON on stderr, and needs no login for anonymous generation.

```bash
npm install -g typeship-ax          # or: npx -y typeship-ax@latest <command>
typeship agent-guide --format json
```

`agent-guide` returns the CLI's conventions, first command, hosted MCP URL, and next steps as JSON. Read it once.

## Step 3: Pick a path

### Path A: no account, generate now

Works with no key. The first 25 operations of the spec, one call at a time, 20 calls a minute per address, nothing stored.

```bash
typeship generate run --spec '{"url":"https://api.example.com/openapi.json"}' --language typescript --out sdk/
# or an inline file:
typeship generate run --spec "{\"inline\":$(jq -Rs . < openapi.yaml)}" --language python --out sdk/
```

`--out` writes the generated files into the directory and prints a summary; without it the full response (files, warnings, meta, limits, claim) prints as JSON. If the response carries `limits`, the spec was capped; tell the user how many operations were left out and that a key lifts it (Path C). If it carries `claim.url` (URL-sourced specs do), give that link to the user: signed in, one click turns this run into a project that regenerates on every spec change. The CLI also notes it in `.typeship/claims.json` and `typeship doctor` lists unclaimed ones.

Platforms: add `--platforms '["sdk","cli"]'` or `'["sdk","mcp"]'` (TypeScript only; Python and Go are SDK-only).

### Path B: the user has a key

`TYPESHIP_TOKEN` is set, or the user pasted a key. Do not paste keys into config files or commit them.

```bash
typeship init --all -k "$TYPESHIP_TOKEN"     # saves the key, installs skills, writes MCP config for detected agents, adds a typeship block to AGENTS.md
typeship whoami                              # (with no key anywhere, `typeship init --all` alone starts Path C's sign-in and then does the same)
```

Then generate (Path A's command, now uncapped by the plan), or create a linked project so the package stays current:

```bash
typeship projects create --name "Acme API" --spec-url https://api.example.com/openapi.json --languages '["typescript"]'
typeship projects generate <project_id>
```

`typeship projects create --help` lists every field (destinations, package names, config, auto_regen).

### Path C: the user needs a key

```bash
typeship init --all          # no key anywhere: prints a sign-in link, waits, mints a key for this machine, then sets the machine up
typeship login --no-browser  # the sign-in alone, when init is not wanted
```

It prints an approval link (and a `browser_approval` JSON event on stderr) and polls. Give the link to the user; they sign in to the console and approve "typeship CLI on <host>" once; the CLI stores the key it is given and prints `{ok: true, method: "browser"}`. No key crosses the conversation. The link lasts ten minutes; if it expires, run it again. `init` carries on with the setup by itself; after `login` alone, continue with Path B.

If the user prefers to create a key themselves, they can at https://typeship.dev/console/keys; they should export it as `TYPESHIP_TOKEN` rather than paste it into the chat.

### Path D: no CLI, REST only

```bash
curl -s https://typeship.dev/api/v1/generate \
  -H "Content-Type: application/json" \
  -d '{"spec":{"url":"https://api.example.com/openapi.json"},"platforms":["sdk"],"language":"python"}'
```

Add `-H "Authorization: Bearer $TYPESHIP_TOKEN"` when a key exists. The response is `{files:[{path,content}], warnings, meta, limits?}`. The full contract: https://typeship.dev/openapi.yaml; reference: https://typeship.dev/docs/api.md.

### Path E: connect this agent to typeship's MCP server

Two doors, one server (Streamable HTTP, MCP 2026-07-28). https://typeship.dev/mcp-oauth signs the user in from the client (RFC 9728 challenge, Clerk as the authorization server, dynamic registration and PKCE): no key exists or is pasted. Use it when a person is present to approve a browser sign-in. https://typeship.dev/mcp takes `Authorization: Bearer ak_...` instead, and without any key still exposes the docs tools (`search_docs`, `read_docs`, `query_docs`, `submit_docs_feedback`) and `generate_run`. Use it headless, in CI, or when a key is already in the environment.

```bash
claude mcp add --transport http typeship https://typeship.dev/mcp-oauth                                              # a person signs in once
claude mcp add --transport http typeship https://typeship.dev/mcp --header 'Authorization: Bearer ${TYPESHIP_TOKEN}'  # headless, with a key
codex mcp add typeship --url https://typeship.dev/mcp-oauth && codex mcp login typeship
typeship mcp install --all      # key-based entry for every agent client found on this machine, key as an env reference
```

## Step 4: Put the package to work

Generated packages carry their own `AGENTS.md` and `api.md` at the package root. Read the package's AGENTS.md before writing code against it. Add the package to the repo the way https://typeship.dev/docs/guides/add-to-your-repo.md describes (same-repo directory or its own repository), and never edit generated files by hand; use spec patches and config (https://typeship.dev/docs/projects/spec-patches.md) so regeneration keeps the change.

## Step 5: Verify

```bash
typeship doctor            # binary, credentials, network, MCP config
ls sdk/ && cat sdk/AGENTS.md | head -40
```

For a TypeScript package: `cd sdk && npm install && npm test`. Python: `python -m compileall`. Go: `go build ./...`.

## Rules

- Never commit a key. `TYPESHIP_TOKEN` in the environment, or the CLI credentials file, only.
- Read the JSON error envelope: `{"status":"error"|"action_required","issues":[{"code","message"}],"docs_url","next_steps":[...]}`. Branch on `issues[].code`, not on the message. `PLAN_LIMIT` and `RATE_LIMITED` are not bugs; do exactly what `next_steps` says and do not retry the same call.
- Do not edit generated files. Change the spec, a spec patch, or the project config, then regenerate.
- If a step fails and the error does not tell you why, run `typeship docs search "<the error>"` before guessing.
- Prefer the CLI in terminals and the MCP server in chat clients; they are the same operations.

## Done

When the package is generated and verified, tell the user, in this shape:

> typeship: generated <language> <platforms> from <spec> into <dir> (<n> operations<, m omitted by the free cap>). <Linked as project <id> | Not linked; run `typeship projects create` to keep it current.> Docs: https://typeship.dev/llms.txt