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.

typeship exposes its own API through the same MCP runtime it generates for customers. The hosted endpoint exposes direct operation tools because typeship's API fits comfortably; the local @typeship-ax/mcp package uses the compact search_docs, read_docs, and execute surface. Both are generated from typeship's Definition and speak stateless MCP 2026-07-28.

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 an account	None; docs and the first 25 operations of 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

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 account, Project, Generation, Definition Revision, and API-key metadata.
`typeship:generate`	Run stateless generation or regenerate a project.
`typeship:write`	Create and update account 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 an account

Connect to https://typeship.dev/mcp/public. It exposes search_docs, read_docs, query_docs, submit_docs_feedback, and generate_run. Generation returns the first 25 operations, is rate limited per address, and carries a clear truncation record and upgrade path. No account tools appear, even if a credential is sent to this endpoint.

Hosted tools

The secured endpoint presents one tool per operation:

Tool	Does
`generate_run`	Generate one Target from a Definition.
`projects_list`, `projects_create`, `projects_retrieve`, `projects_update`, `projects_delete`	Manage Projects, Target selection, Deliveries, and generated-client configuration.
`projects_generate`	Generate every selected Target for a Project.
`projects_list_generations`, `generations_retrieve`, `generations_retrieve_file`	Read history, one generation, or one generated file.
`definitions_retrieve`, `definitions_update`	Read or change a Project's Definition.
`definition_revisions_list`, `definition_revisions_retrieve`, `definition_revisions_retrieve_content`	Inspect immutable Definition history.
`account_retrieve`	Read the account and plan behind the credential.
`api_keys_list`, `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.

Requests count against the same limits as direct API calls; MCP tool calls are also capped at 120 per minute per caller.

Local package

npm install -g @typeship-ax/cli
typeship login
claude mcp add typeship -- npx -y --package @typeship-ax/mcp typeship-mcp

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 complete contract 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 an SDK, CLI, or MCP package from an OpenAPI or GraphQL document.
Create and configure a project and its GitHub delivery destinations.
Apply a Definition patch, regenerate, and inspect the resulting release candidate.
Read the exact Definition Revision and source document behind a Generation.

Creating an API key is deliberately not an MCP tool. A person approves it in the console or through the typeship CLI's browser flow.

MCP server