Config

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.

{
  "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.

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".

Resolution at runtime is per-call option, then the operation's policy, then the root policy, then the SDK defaults. See 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".

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.

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 alike. See 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.

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.

{
  "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.

{
  "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.

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.