--- title: "MCP server" description: "Let a coding agent drive typeship through one secured hosted connection, an explicit public connection, or a focused local package." url: https://typeship.dev/docs/mcp markdown: https://typeship.dev/docs/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 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 ```bash 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: ```json { "mcpServers": { "typeship": { "type": "http", "url": "https://typeship.dev/mcp" } } } ``` The challenge names the endpoint's [protected-resource metadata](https://typeship.dev/.well-known/oauth-protected-resource). 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: ```bash 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 ```bash 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. ## Sitemap [Every page of these docs](https://typeship.dev/llms.txt)