--- title: "Config" description: "Everything typeship needs beyond the spec, in one object: global parameters, retry tuning, pagination rules, and how the generated CLI and MCP server behave." url: https://typeship.dev/docs/projects/config markdown: https://typeship.dev/docs/projects/config.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. # Config Everything typeship needs beyond the spec, in one object: global parameters, retry tuning, pagination rules, and how the generated CLI and MCP server behave. Some things a spec cannot say. Which parameters every call carries. Which statuses your API wants retried. How a list endpoint pages when the shape is unusual. Which endpoint `whoami` should call, and where your docs live. A project's config holds all of it, outside the spec. Nothing is written into your OpenAPI document, so there are no vendor extensions to maintain and nothing to strip before publishing the spec. Config is one object. Set it in project settings, or with the `config` field on the [typeship API](https://typeship.dev/docs/typeship-api/api). > **For AI agents:** `typeship projects update --config '{"retries":{...},"pagination":{...},"cli":{...},"mcp":{...},"docs_url":"https://docs.acme.example"}'` > > replaces the whole object, so send every key you want kept. The same > > `--config` > > works on > > `typeship generate run` > > for a one-off. The console and the API use the same snake\_case shape, so a block is copyable between them, and the same object works as `config` on an ad hoc `POST /v1/generate`. ```json { "globals": ["account_id", "api-version"], "retries": { "max_retries": 3, "statuses": [429, 503], "initial_delay_ms": 500, "max_delay_ms": 8000, "operations": { "createCharge": { "retry_non_idempotent": true }, "GET /health": { "disabled": true } } }, "pagination": { "listEvents": { "style": "cursor", "items_field": "records", "cursor_param": "after", "next_cursor_field": "next" }, "GET /audit": false }, "cli": { "whoami_operation": "users.me", "oauth_client_id": "acme-cli", "oauth_scopes": ["read", "offline_access"], "support_url": "https://github.com/acme/acme-node/issues/new" }, "mcp": { "tool_mode": "auto" }, "graphql": { "endpoint": "https://api.acme.example/graphql", "auth": "basic" }, "docs_url": "https://docs.acme.example" } ``` `globals`, `retries`, `pagination`, `graphql`, and `docs_url` apply to every language and every platform in the project. `cli` and `mcp` configure the CLI and the MCP server, which are TypeScript artifacts, and the console shows them under those platforms. Names under `globals`, `retries`, and `pagination` that match nothing in the spec produce a warning on the generation, so a typo cannot silently do nothing. The `cli`, `mcp`, and `docs_url` half is validated when you save: a bad URL or an unknown tool mode is rejected outright. ## Global parameters `globals` lists the wire names of query or header parameters that every call should carry. Each becomes a client option, typed from the parameter's schema, applied to every operation that accepts it, with per-call values winning. Up to 20. ```ts const client = new AcmeClient({ accountId: "acct_123", apiVersion: "2026-08" }); ``` The generated CLI reads the same values from `ACME_ACCOUNT_ID`-style environment variables and accepts `--account-id` per invocation. The MCP server reads the environment variables. Path parameters cannot be globals. Signatures stay positional. ## Retry tuning `retries` sets the root policy and, under `operations`, overrides keyed by `operationId` or `"METHOD /path"`. | Field | Meaning | | ---------------------------------- | ------------------------------------------------------------------------------ | | `max_retries` | Retries after the first attempt. 0 to 10. | | `statuses` | Replaces the default retryable set (`408`, `429`, `500`, `502`, `503`, `504`). | | `initial_delay_ms`, `max_delay_ms` | The backoff window. | | `retry_non_idempotent` | Retry POST and PATCH too. | | `disabled` | No retries for this scope. | Resolution at runtime is per-call option, then the operation's policy, then the root policy, then the SDK defaults. See [Retries and timeouts](https://typeship.dev/docs/platforms/sdk#retries-and-timeouts). ## Pagination rules Pagination detection is heuristic. When it guesses wrong for an endpoint, or your API pages in a way it does not recognize, pin the rule under `pagination`, keyed by `operationId` or `"METHOD /path"`. | Field | Meaning | | ----------------------------------------------------------------- | -------------------------------------------------------------------- | | `style` | `cursor`, `cursorFromLastId`, `page`, or `offset`. Default `cursor`. | | `items_field` | The array property holding items. Required. | | `cursor_param`, `next_cursor_field`, `has_more_field`, `id_field` | Cursor styles. | | `page_param`, `offset_param`, `limit_param` | Page and offset styles. | Set a key to `false` to turn pagination off for that operation. Malformed or unmatched rules fall back to detection with a warning. Up to 100 keys. ## Generated CLI `cli` shapes the commands your CLI ships with. Under **generated tooling** in project settings. | Field | Effect | | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `whoami_operation` | Pins the `resource.method` that `whoami` calls when auto-detection picks the wrong endpoint. | | `oauth_client_id`, `oauth_scopes`, `oauth_audience` | Enable the device-flow `login` and shape its token request. Include `offline_access` in the scopes if your authorization server gates refresh tokens behind it. | | `update_notice` | Opts the CLI into a once-a-day registry check that suggests `upgrade`. Off by default, so the CLI never phones home unless you say so. | | `support_url` | The target of the `feedback` command. GitHub issue URLs get a prefilled title and environment details. | ## MCP server `mcp.tool_mode` is `auto`, `operations`, or `meta`. `meta` collapses per-operation tools into `search_docs`, `read_docs`, and `execute` so large APIs do not flood an agent's context window. `auto` switches to `meta` above 100 operations. It applies to the server in your package and to the [hosted endpoint](https://typeship.dev/docs/platforms/mcp#hosted-endpoint) alike. See [Tool mode for large APIs](https://typeship.dev/docs/platforms/mcp#tool-mode-for-large-apis). `mcp.instructions` is text appended to the server's instructions, which agents read once when they connect: what to call first, conventions the spec does not state, what not to do. Up to 2,000 characters. The package's server and the hosted endpoint both carry it. See [Instructions for agents](https://typeship.dev/docs/platforms/mcp#instructions-for-agents). `mcp.tool_descriptions` is an object keyed by operationId or `"METHOD /path"` whose values replace the tool description typeship derives for that operation, for flows the spec cannot describe (a multi-step upload, a slow report). Up to 200 keys of 600 characters. Keys that match no operation are reported as generation warnings. ```json { "mcp": { "tool_descriptions": { "createUpload": "Step 1 of 3: reserve a slot, PUT the bytes to upload_url, then call uploads_finish.", "GET /reports": "Slow (10 to 30 s); pass fields to keep the result small." } } } ``` ## GraphQL schemas A GraphQL schema says nothing about where it is served or how requests authenticate, so `graphql` carries both. It is ignored for OpenAPI specs. ```json { "graphql": { "endpoint": "https://payments.braintree-api.com/graphql", "environments": [ { "name": "sandbox", "url": "https://payments.sandbox.braintree-api.com/graphql" }, { "name": "production", "url": "https://payments.braintree-api.com/graphql" } ], "auth": "basic", "title": "Braintree" } } ``` `endpoint` becomes the generated client's default `baseUrl`. It defaults to the spec URL when that URL is the endpoint itself. `environments` name additional endpoints, each a client environment. `auth` is `bearer` (the default, sent as `Authorization: Bearer`), `basic` for key-pair APIs where the public key is the username and the private key the password, `api_key` with `api_key_header` for a header, or `none`. `title` names the package and client (`braintree`, `BraintreeClient`) and defaults to a name taken from the endpoint's host. See [Generate from GraphQL](https://typeship.dev/docs/guides/graphql). ## Docs site `docs_url` is your API's documentation site. Three surfaces read it through your site's `llms.txt`: the CLI's `docs` command, the MCP server's `search_docs` and `read_docs` tools, and the package's `AGENTS.md`. It defaults to the spec's `externalDocs.url`. Most docs hosts publish `llms.txt` and `llms-full.txt` automatically. ## Replace, do not merge On the API, `config` replaces the whole object. Send every key you want kept, and `null` to clear everything. The console does the same on save. ## Sitemap [Every page of these docs](https://typeship.dev/llms.txt)