--- title: "MCP server" description: "Let a coding agent drive typeship: generate packages, create and configure projects, trigger regeneration, and read results, all as tools. Hosted at typeship.dev/mcp, or local from the typeship package." url: https://typeship.dev/docs/typeship-api/mcp markdown: https://typeship.dev/docs/typeship-api/mcp.md section: "Get started" --- > ## Documentation index > Fetch the complete documentation index at https://typeship.dev/llms.txt (every page, one line each) or the full text at https://typeship.dev/llms-full.txt. > Append .md to any docs URL, or send Accept: text/markdown, for the markdown twin of that page. # MCP server Let a coding agent drive typeship: generate packages, create and configure projects, trigger regeneration, and read results, all as tools. Hosted at typeship.dev/mcp, or local from the typeship package. typeship's MCP server exposes typeship's own API as tools: one per operation, typed input schemas, `search_docs` and `read_docs` over these docs. It is generated by typeship from its own spec, so it behaves like the MCP servers typeship generates for your API. Everything on the [MCP server](https://typeship.dev/docs/platforms/mcp) platform page applies. There are two ways to run it. The hosted endpoint needs nothing installed: `https://typeship.dev/mcp-oauth` signs you in from the client, `https://typeship.dev/mcp` takes an API key. The local server, `typeship-mcp`, ships in the `typeship-ax` npm package for clients that want stdio (`npx -y typeship-ax typeship-mcp` runs it without installing). Both are listed in the [official MCP registry](https://registry.modelcontextprotocol.io/v0/servers?search=typeship) as `dev.typeship/typeship`, so a client that browses the registry can add typeship by name. ## Hosted endpoint Streamable HTTP, MCP 2026-07-28, at `https://typeship.dev/mcp-oauth`. Connect, and the client opens a browser: sign in once, and the connection acts as you. No key is created, copied, or pasted. ```bash claude mcp add --transport http typeship https://typeship.dev/mcp-oauth ``` Codex CLI: `codex mcp add typeship --url https://typeship.dev/mcp-oauth`, then `codex mcp login typeship`. VS Code, one click: [Add typeship to VS Code](vscode:mcp/install?%7B%22name%22%3A%22typeship%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Ftypeship.dev%2Fmcp-oauth%22%7D). Claude Desktop and claude.ai: add `https://typeship.dev/mcp-oauth` as a custom connector (Settings, Connectors). Any client that reads a JSON config (`.mcp.json` for Claude Code, `.vscode/mcp.json` for VS Code, and most others): ```json { "mcpServers": { "typeship": { "type": "http", "url": "https://typeship.dev/mcp-oauth" } } } ``` Under the hood: an unauthenticated request is answered with an RFC 9728 challenge naming the endpoint's [metadata](https://typeship.dev/.well-known/oauth-protected-resource/mcp-oauth); the authorization server is typeship's Clerk instance, which supports dynamic client registration and PKCE, so a current MCP client completes the flow with nothing configured in advance. The access token it comes back with is accepted by the [API](https://typeship.dev/docs/typeship-api/api) directly, too. No tools are gated by scope: a signed-in connection can do what a key can. If you belong to several organizations, choose the one signed-in agents act in under **API keys → Signed-in agents** in the console (or send `X-Typeship-Org: org_...` with each request). Until you do, tools that need an organization answer `organization_required` and name the choice. A member of one organization has nothing to choose. ### With a key, for CI and headless agents The same server at `https://typeship.dev/mcp` takes an API key instead, carried as an environment reference so it never lands in a config file. This is the form for pipelines, and for an agent with no browser to hand: ```bash export TYPESHIP_TOKEN=ak_... claude mcp add --transport http typeship https://typeship.dev/mcp \ --header 'Authorization: Bearer ${TYPESHIP_TOKEN}' ``` The single quotes matter: Claude Code stores the reference and expands `${TYPESHIP_TOKEN}` when it connects, so the key stays in your environment. Codex: `codex mcp add typeship --url https://typeship.dev/mcp --bearer-token-env-var TYPESHIP_TOKEN`. `typeship mcp install --all` writes this entry into every client on the machine (`--vscode`, `--windsurf`, and the rest for one). As JSON: ```json { "mcpServers": { "typeship": { "type": "http", "url": "https://typeship.dev/mcp", "headers": { "Authorization": "Bearer ${TYPESHIP_TOKEN}" } } } } ``` Requests through the hosted endpoint count against the same limits as direct API calls (see [Rate limits](https://typeship.dev/docs/typeship-api/api/rate-limits)); tool calls themselves are capped at 120 per minute per caller. The endpoint speaks the current MCP protocol only, like every server typeship generates. A client that still needs the legacy `initialize` handshake gets an error naming the version it must support. ### Without a key Connect with no `Authorization` header and the server still answers, with the docs tools (`search_docs`, `read_docs`, `query_docs`, `submit_docs_feedback`) and `generate_run`. `generate_run` behaves like the [generator on the homepage](https://typeship.dev/): the first 25 operations of a spec, rate limited per address, nothing stored. That is enough for an agent that has a spec and no typeship account to produce a package. Every other tool answers with a message naming the key it needs and where to create one, and never retries anything upstream. Requests through the hosted endpoint count against the same limits as direct API calls (see [Rate limits](https://typeship.dev/docs/typeship-api/api/rate-limits)); tool calls themselves are capped at 120 per minute per caller. ## Local server ```bash npm install -g typeship-ax # or: npx -y typeship-ax typeship-mcp typeship login --token ak_... typeship mcp --claude # ./.mcp.json typeship mcp --cursor # ./.cursor/mcp.json typeship mcp --claude-desktop # Claude Desktop ``` The local server reads the credentials `typeship login` saved, or `TYPESHIP_TOKEN` from its environment. No token goes into the config file. See [Connect MCP clients](https://typeship.dev/docs/guides/mcp-clients) for manual configuration. ## Tools One per operation, named `resource_method`: | Tool | Does | | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `generate_run` | Generate a package from a spec URL or inline text. Nothing is stored. Works without a key. | | `projects_list`, `projects_create`, `projects_get`, `projects_update`, `projects_delete` | Manage projects, including languages, destinations, spec patches, config, and hosted toggles. | | `projects_generate` | Regenerate a project and return every language's files. | | `projects_list_generations`, `generations_get`, `generations_get_file` | Read history, a generation, or one file. | | `spec_versions_list`, `spec_versions_get`, `spec_versions_get_content` | The spec audit trail. | | `account_me`, `account_update`, `usage_retrieve` | Account, defaults, allowance. | | `api_keys_list`, `api_keys_revoke` | Key hygiene. | | `search_docs`, `read_docs` | Search and read these docs and the API reference from inside the session. Work without a key. | | `query_docs` | Grep every docs page and both references with a regular expression; matching lines with their page and context. Works without a key. | | `submit_docs_feedback` | Tell the typeship team a page is wrong, missing, or unclear. Works without a key. | ## What an agent can do with it * "Generate a Python SDK for this OpenAPI URL and save the files under `sdk/`." * "Create a typeship project for our API with TypeScript and Go, pointed at these two repos, and turn on auto-regen." * "Add a spec patch that retypes every `account_id` to string, then regenerate and tell me what changed." * "How many hosted generations do we have left this month?" Because `read_docs` returns these docs, an agent can also answer questions about how typeship works without leaving the session. ## Not available as tools Creating an API key. That is console-only, on purpose. ## Sitemap [Every page of these docs](https://typeship.dev/llms.txt)