MCP server for the Typeship API

Let a coding agent drive Typeship through one secured hosted connection, an explicit public connection, or a focused local package.

Use the Typeship MCP server to generate packages and manage Projects from an agent. The hosted endpoint exposes individual operation tools; the local @typeship-ax/mcp package provides search_docs, read_docs, and execute. Both support MCP 2025-11-25 and 2026-07-28 automatically.

Choose a hosted endpoint

Endpoint	Use it for	Authentication
`https://typeship.dev/mcp`	Normal interactive or automated access	OAuth, or `Authorization: Bearer ak_...`
`https://typeship.dev/mcp/readonly`	Agents that may inspect but never mutate	OAuth with organization + read access, or an API key; the server still exposes only reads
`https://typeship.dev/mcp/public`	Trying Typeship without signing in	None; docs and 25-operation anonymous generation only

There is one secured URL. A current MCP client connects to /mcp, receives an RFC 9728 challenge, opens a browser, and returns with a delegated token. The same URL accepts an organization API key for CI and headless automation. /mcp/public is separate so an accidental anonymous connection cannot look authenticated, and /mcp/readonly remains narrow even if its credential has more authority.

Connect with OAuth

claude mcp add --transport http typeship https://typeship.dev/mcp

Use the client’s default protocol settings. See client compatibility for supported versions and configuration locations.

Codex CLI: codex mcp add typeship --url https://typeship.dev/mcp, then codex mcp login typeship. Claude Desktop and claude.ai: add https://typeship.dev/mcp as a custom connector. JSON clients:

{ "mcpServers": { "typeship": { "type": "http", "url": "https://typeship.dev/mcp" } } }

The challenge names the endpoint's protected-resource metadata. The OAuth flow supports dynamic client registration or client-ID metadata discovery, PKCE, consent, and token refresh. Consent requests four capabilities:

Scope	Grants
`user:org:read`	Choose the organization this grant is bound to.
`typeship:read`	Read Organization, Project, Generation, Spec Revision, and API-key metadata.
`typeship:generate`	Run one-shot generation or regenerate a project.
`typeship:write`	Create and update Organization resources.

The consent screen includes a Typeship organization selector. The selected org_id is authoritative for the lifetime of that grant, with no request-header override. Typeship revalidates current membership and role before use.

The MCP tool catalogue contains only operations the token may execute. If a call needs a capability the token lacks, the server returns HTTP 403 with WWW-Authenticate: Bearer error="insufficient_scope" and the scope to request. That transport-level response lets an MCP client repeat OAuth with elevated consent. Invalid, expired, or revoked tokens return HTTP 401 before tools are listed.

/mcp/public is credential-neutral. It ignores an Authorization header if a client sends one accidentally, always applies anonymous limits, and attributes rate limits to the caller's address. Use /mcp when a credential should affect access or quota.

Scopes do not elevate organization roles. Project deletion still requires an organization admin. Members may revoke API keys they created; admins may revoke any organization key.

Connect with an API key

The same /mcp endpoint accepts an organization API key:

export TYPESHIP_TOKEN=ak_...
claude mcp add --transport http typeship https://typeship.dev/mcp \
  --header 'Authorization: Bearer ${TYPESHIP_TOKEN}'

The single quotes keep the environment reference in Claude's configuration instead of copying the key. Codex: codex mcp add typeship --url https://typeship.dev/mcp --bearer-token-env-var TYPESHIP_TOKEN. typeship mcp install --all writes key-based entries for the clients it finds. API keys carry the organization's complete authority; use OAuth when a person can consent and least privilege matters.

Try it without signing in

Connect to https://typeship.dev/mcp/public. It exposes search_docs, read_docs, query_docs, submit_docs_feedback, packages_generate, and packages_download. Generation includes 25 operations and is rate limited per address. Check coverage for omitted operations. No organization tools appear, even if a credential is sent to this endpoint.

Get the generated package

Call packages_generate with a Spec and Target. On the local package, call execute with operation: "packages_generate". A runnable Spec is https://typeship.dev/examples/petstore/openapi.yaml.

The result includes download.url, download.sha256, download.file_count, and download.expires_at. The hosted server returns this reference with the generation metadata and warnings. For a compact local result, pass fields: ["download", "meta", "warnings", "limits", "claim"] inside the operation arguments.

Download the ZIP before its expiry, verify its SHA-256 checksum, and extract it into an empty directory. Every file from that exact generation is included, even when the files exceed the MCP response limit. Follow the extracted README to build and use the package. Downloading does not run generation again or consume another generation allowance.

On the local package, execute with operation: "packages_download" and the token from download.url saves the ZIP to disk and returns its path. For a hosted connection, use your agent's file-download or terminal tool to save download.url to your workspace.

Anyone with the download URL can retrieve the package, so keep it private. It expires with the original 24-hour replay window; downloading does not extend that window. An expired link returns 404. Run a new generation to obtain a new link, which may reflect a changed Spec. The separate claim.url saves an eligible anonymous recipe as a Project; it is not a package download.

Hosted tools

The secured endpoint presents one tool per operation:

Tool	Does
`projects_create`, `projects_list`, `projects_get`, `projects_update`, `projects_delete`	Manage Projects and their shared configuration.
`projects_generate`	Generate every active Target and poll until each Target's files succeed or fail.
`specs_get`, `specs_update`, `specs_refresh`	Read or change a Project's Spec, or fetch its configured source and queue automatic generation.
`spec_revisions_list`, `spec_revisions_get`, `spec_revisions_list_files`	Inspect Spec history, Diagnostics, and source files.
`targets_create`, `targets_list`, `targets_get`, `targets_update`, `targets_delete`	Manage Targets and their Deliveries.
`deliveries_create`, `deliveries_list`, `deliveries_get`, `deliveries_update`, `deliveries_delete`	Check or change where packages go.
`generations_get`, `generations_list`, `generations_list_files`	Read Generation history, one Generation, or its files.
`drafts_list`, `drafts_get`, `drafts_update`, `drafts_list_files`, `drafts_resolve`, `drafts_recover`	Read a Draft, select its version, and review custom code, conflicts, and history recovery.
`releases_list`, `releases_get`, `releases_retry`, `targets_adopt`	Read releases, retry publishing, or adopt an existing package.
`files_get`	Read one file from a Spec Revision, Generation, or Draft in bounded chunks.
`packages_generate`	Generate one package from a Spec.
`packages_download`	Download the complete ZIP from an unexpired one-shot generation.
`organization_get`	Read the organization and plan behind the credential.
`api_keys_list`, `api_keys_get`, `api_keys_revoke`	Inspect keys and revoke one within the caller's authority.
`search_docs`, `read_docs`, `query_docs`, `submit_docs_feedback`	Find, read, grep, and report problems in Typeship documentation.

Every tool call counts toward a limit of 120 per minute per caller. Tools that call the Typeship API, which is all of them except the docs tools, also count toward the API's rate limits, so an authenticated caller can make at most 60 of those per minute.

Local package

Connect with the client’s default settings; no protocol environment variables are required.

typeship --version
typeship login
claude mcp add typeship -- npx -y --package @typeship-ax/mcp typeship-mcp
claude mcp list

The status should report Connected. If it reports an unsupported protocol version, update the client and the generated package.

The client launches the focused package over stdio. It reads credentials saved by typeship login, or TYPESHIP_TOKEN, and presents three stable tools:

Tool	Does
`search_docs`	Search operation names, paths, descriptions, arguments, and guide prose.
`read_docs`	Read one operation's arguments, example, and result shape (`schema: true` adds its full JSON Schemas), or one guide page.
`execute`	Call an operation by name; destructive operations require `confirm: true`.

An operation such as projects_delete is the operation argument to execute; it is not a direct local tool. Use discovery, read the contract, then execute.

What an agent can do

Generate a CLI, MCP, or SDK package from an OpenAPI or GraphQL document.
Create and configure a project and its GitHub delivery destinations.
Apply a Spec patch, regenerate, and inspect the resulting Draft.
Read the Spec Revision and source file behind a Generation.

API keys cannot be created through MCP. A person approves each key in the console or through the Typeship CLI's browser flow.

Typeship MCP server

On this page