Configuration reference

Configuration sets generated-client behavior that your Spec does not describe, such as retry policy, customer login, and documentation URLs. Set shared defaults on the Project and override them for individual Targets. Configuration does not modify your source spec.

Use this page to look up fields. For a task walkthrough, see customer authentication, SDK customization, or connecting your guides.

Config is one object with two scopes. Project.config is inherited by every Target. Target.config is an optional override for one independently generated surface. Top-level Target values replace their Project default; auth, cli, mcp, readme, and package merge by field. An explicit false can override true for retry settings and CLI update notices. GraphQL source settings are the exception: they live only on the Spec and cannot be overridden by a Target.

The Console and API use the same snake_case shape, so a block is copyable between them. GET /projects/{project_id} returns the shared config; every Target returns only its override; Generations record the resulting package and source revision, not the resolved configuration.

Write only the settings you need, but preserve existing keys when updating a stored object. For example, this retry policy is complete for a Project with no other configuration:

{ "retries": { "max_retries": 3, "statuses": [429, 503] } }

globals, retries, pagination, readme, package, docs_url, and docs_index_url can be shared by the Project or overridden per Target. cli and mcp configure their generated tooling wherever those settings are relevant. Names under globals, retries, pagination, and readme that match nothing in the Spec produce a generation warning, so a typo cannot silently do nothing. Tooling and package metadata are validated when you save: bad URLs, unsafe executable names, and unknown tool modes are rejected outright.

README quickstart

Typeship normally chooses a low-friction operation for the README's first call. Set readme.quickstart_operation to an operationId or "METHOD /path" when another operation better explains the API. The choice applies to each generated language where that call remains copyable using only credentials and generated path placeholders. An operation outside the plan cap, one with other required inputs, or one the target language cannot express produces a generation warning and keeps the automatic example. Full examples for every operation remain in api.md.

Select operations

include and exclude generate part of an API, such as one product area of a large Spec. Each entry is a tag name, a path glob, or an HTTP method followed by a path glob:

{
  "include": ["/zones/**", "/accounts/*/workers/**"],
  "exclude": ["DELETE /zones/*"]
}

In a path glob, * matches one path segment (including a placeholder such as {zone_id}) and ** matches any number of segments, so /zones/** covers /zones and everything below it. Tag names match case-insensitively. An operation is generated when it matches an include entry (or there is no include) and no exclude entry. Up to 100 entries each.

Typeship applies the selection to the Spec before its size limit and removes components nothing references any more. A one-shot POST /generate with spec.url can therefore generate part of a Spec up to 64 MB; a Project's Spec is stored whole, so it must stay within 10 MB, and the selection narrows what each Target generates. The generation reports how many operations were kept, and warns about an entry that matches nothing. A selection that keeps no operation fails with spec_invalid. include and exclude apply to OpenAPI and Swagger Specs, not GraphQL.

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 ParcelClient({ accountId: "acct_123", apiVersion: "2026-08" });

The generated CLI reads the same values from PARCEL_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".

Without an applicable Retry-After, the runtime chooses a random delay between zero and the smaller of initial_delay_ms × 2^attempt and max_delay_ms. These values bound jitter; they are not fixed sleep durations. TypeScript (including generated CLI/MCP) and Go accept numeric seconds or an HTTP date in Retry-After; Python accepts numeric seconds. A positive parsed header takes precedence over backoff and is capped at 60 seconds, independently of max_delay_ms.

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. Up to 100 keys. Invalid configuration, such as a missing items_field or unsupported style, is rejected when saved; inspect the update error response. A structurally valid rule that cannot match the operation or response produces a Generation warning and falls back to detection; inspect that Generation’s warnings.

String and numeric cursors are supported, including zero. In Go, an object, array, or boolean cursor fails the iterator; inspect Err() after iteration. For cursor, a missing, empty, null, or unchanged next cursor ends iteration. cursor_from_last_id advances with the last item's ID and stops on an empty page or missing ID. Page and offset styles advance by one page or the returned item count; without a false has_more_field or a supplied limit indicating the end, an empty page stops iteration.

For example, the fictional Parcel API's listShipments operation accepts an after query parameter and returns:

{
  "records": [{"shipment_id": "shp_123"}],
  "next": "cursor_456"
}

Add this mapping to your configuration, preserving all other stored keys:

{
  "pagination": {
    "listShipments": {
      "style": "cursor",
      "items_field": "records",
      "cursor_param": "after",
      "next_cursor_field": "next"
    }
  }
}

The client yields items from records, reads next from the response, then sends ?after=cursor_456 on the following request. The final response sets next to null. Saving config replaces its stored object, so retrieve the existing configuration and merge this fragment into it before updating.

Authentication

Open Authentication in your Project to review the API credentials detected from the Spec and configure customer sign-in for the generated CLI and local MCP server. SDKs do not use this sign-in flow; the application using an SDK supplies credentials at runtime.

The public auth object is organized by responsibility:

Keep access tokens, refresh tokens, API keys, and client secrets in the application runtime or user credential store. Typeship rejects them from stored configuration.

The Console edits the OAuth server, each application's name, login method, client ID, and callback URL, and the identity mapping. Set organization_parameter, client_auth_method, approval_url, environments, credential_variables, and credential_parameters in the Project's config through the Typeship API.

Configure CLI and local MCP sign-in

Register a public OAuth application for the generated CLI. The CLI uses Authorization Code with PKCE and cannot keep a client secret. A compatible local MCP server can reuse its saved session.

{
  "auth": {
    "oauth_server": {
      "issuer": "https://auth.parcel.example",
      "scopes": ["openid", "offline_access", "records:read"],
      "resource": "https://api.parcel.example"
    },
    "oauth_applications": {
      "desktop": {
        "client_id": "parcel-desktop",
        "login_method": "browser",
        "redirect_uri": "http://127.0.0.1:43821/callback"
      }
    },
    "oauth_application": "desktop"
  }
}

Discovery supplies the authorization and token endpoints. Set discovery_url, authorization_url, token_url, or device_authorization_url under oauth_server only when discovery does not describe them correctly. Use audience or resource only when your provider requires that parameter.

An explicit runtime credential wins over interactive login. Without OAuth settings, approval_url can point to a custom challenge-and-poll service. See Add browser login for the full flow.

Confirm the signed-in account

Choose an authenticated REST GET or GraphQL query with no required arguments, then map the stable IDs it returns:

{
  "auth": {
    "identity_verification": {
      "operation": "me.get",
      "subject_field": "/id",
      "account_field": "/account_id",
      "organization_field": "/organization_id"
    }
  }
}

The operation must require a supported credential combination. For GraphQL, pointers start inside the selected query result. Each mapped field must return a nonempty string or safe integer; an organization may return null for a personal account.

Keep at least one non-null mapping in identity_verification. Set an individual mapping to null to clear it while retaining another, or set identity_verification itself to null to remove the whole policy. An empty object, an operation without mappings, or an object containing only null mappings is invalid. Saving config replaces its whole stored object, so include the other settings you want to keep.

The CLI checks this identity before saving a new login and after refreshing it. login --account, --subject, and --organization can require an expected value. These flags verify the API response; they do not choose an account at the provider or grant access.

Let customers choose an organization

Map organization_field to the stable organization ID returned by your API. When the provider accepts an organization parameter during authorization, set organization_parameter on the selected OAuth application to organization or organization_id.

Customers can then run login --login-organization org_123. The CLI sends that value to the provider and saves the session only when your authenticated identity read returns the same organization ID. Your provider and API still own membership checks and authorization; this option does not grant access by itself.

Verify the setup

After saving an OAuth application and identity mapping, open Verify setup in the Console and choose a saved CLI or MCP Target. A credential check sends an existing test credential to Typeship for one anonymous and one authenticated identity read. A browser check downloads a ten-minute, single-use file that the generated CLI uses to complete its native OAuth flow before Typeship performs the same API checks.

Typeship records the check result without retaining the credential, expected ID, or response body. A later Spec or authentication change marks the result stale. The check confirms login and one identity read; separately test refresh, revocation, and an operation outside the grant's scope.

Use more than one OAuth application

Store each OAuth application once under oauth_applications. The Project's oauth_application is the default. A Target can select another Project-owned application:

{
  "auth": {
    "oauth_application": "internal"
  }
}

Target authentication is limited to oauth_application and environment-specific application selection. A Target cannot redefine the Project's OAuth server, application catalog, scopes, or identity policy.

Configure sandbox and production

Environment names come from the Spec's servers. Use them to select another application, scope set, audience, or API resource:

{
  "auth": {
    "environments": {
      "sandbox": {
        "oauth_application": "sandbox",
        "scopes": ["openid", "sandbox:read"],
        "resource": "https://sandbox.api.parcel.example"
      }
    }
  }
}

A generated client selects the API URL and its authentication settings together. Credentials still come from the application or selected CLI profile. Keep separate profiles for production and sandbox.

Configure a machine client

A backend application may use a confidential OAuth application and a client-credentials grant. Store its client ID and how it authenticates to the token endpoint in oauth_applications; supply the client secret only through the consuming application's runtime options or environment.

{
  "auth": {
    "oauth_applications": {
      "backend": {
        "client_id": "parcel-backend",
        "client_auth_method": "basic"
      }
    }
  }
}

client_auth_method is post (the default, sending the ID and secret in the form body) or basic (an Authorization: Basic header). A Target selects the application with oauth_application. The generated SDKs and MCP server use it only when your application supplies the secret.

Generated machine clients refuse token-endpoint redirects, use HTTPS except on loopback, bound response size and duration, and cache tokens in memory until shortly before expiry. A configured client ID alone never starts a machine grant or replaces a saved CLI login.

Protect a self-hosted MCP server

Connection authorization for a generated MCP server deployed over HTTP is separate from credentials used to call your API. Configure it under mcp.access:

{
  "mcp": {
    "access": {
      "issuer": "https://auth.parcel.example",
      "resource": "https://mcp.parcel.example",
      "scopes": ["mcp:connect"]
    }
  }
}

The generated handler validates the connection token against this issuer, resource, and scope set. jwks_url is optional; otherwise it discovers signing keys from the issuer. Your application supplies separate upstream API credentials through credentialsFor(principal); the MCP connection token is never reused as an API credential.

mcp.access does not apply to the Typeship-hosted endpoint. That endpoint accepts a caller-supplied API credential and forwards it to your API. It has no separate MCP connection token.

See MCP authentication for the HTTP handler and opaque-token introspection options.

Name credential variables

The generated CLI, MCP server, and the Python and Go SDKs read credentials from environment variables named after your package. The name follows the API where the Spec implies it: a bearer scheme named for an API key reads PARCEL_API_KEY, and any other bearer credential reads PARCEL_TOKEN. To choose names yourself, set credential_variables, keyed by security scheme name:

{
  "auth": {
    "credential_variables": {
      "bearerAuth": "PARCEL_TOKEN",
      "partnerBasic": { "username": "PARCEL_PARTNER_ID", "password": "PARCEL_PARTNER_SECRET" }
    }
  }
}

A token or API-key scheme takes one uppercase name; a Basic scheme takes username and password names, or one name when its credential is a single API key sent as the username with an empty password. This setting wins over a scheme's x-typeship-env extension. A key that names no supported scheme, or the wrong shape for the scheme, produces a generation warning and is ignored. The CLI keeps PARCEL_TOKEN, PARCEL_USERNAME, and PARCEL_PASSWORD for now.

Leave out credential parameters

Some Specs repeat the credential as an ordinary parameter, such as a required token header beside a bearer scheme. Typeship leaves such a parameter out of generated signatures, CLI flags, and MCP tool input, because the configured credential already reaches the API through the security scheme. See Authentication for how it recognizes them. Use credential_parameters to correct a decision, keyed by operationId, "METHOD /path", or "*" for every operation, then by the parameter's wire name:

{
  "auth": {
    "credential_parameters": {
      "*": { "token": true },
      "verifyToken": { "token": false }
    }
  }
}

true leaves the parameter out; false keeps it. An operation entry wins over "*", and this setting wins over a parameter's x-typeship-credential extension. An operation key that matches nothing produces a generation warning.

Generated CLI

cli shapes the commands your CLI ships with. Under generated tooling in project settings.

Package metadata

The package object sets metadata included in generated packages.

Repository metadata is derived separately for each language from its destination. A project that publishes TypeScript, Python, and Go therefore links every registry page to the repository that actually contains that package.

MCP server

mcp.registry_name is the stable identity used when you publish the generated server to the MCP Registry. It is independent of the server's implementation language and distribution format.

mcp.tool_mode is auto, operations, or meta. Set a Target to auto to select its tool shape automatically even when its Project specifies another mode. Omit the field to inherit the Project's mode. meta collapses per-operation tools into search_docs, read_docs, and execute so large APIs do not flood an agent's context window. auto uses the serialized tool schemas, switching when the per-operation tool list would exceed 40,000 characters (about 10,000 tokens) or the API exceeds 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."
    }
  }
}

mcp.reference_resolvers controls human-readable MCP arguments without changing the Spec. It is keyed first by the requested operation's operationId or "METHOD /path", then by its argument name. A resolver names one read collection in via, one to four exact-match item fields in match, and optionally the item ID field in id (default id). Set an argument to false to disable both a source-declared resolver and automatic inference. Invalid or unmatched operation, argument, resolver, or field names produce generation warnings.

{
  "mcp": {
    "reference_resolvers": {
      "createShipment": {
        "recipient_id": { "via": "listRecipients", "match": ["name", "email"], "id": "id" }
      },
      "DELETE /shipments/{shipment_id}": {
        "shipment_id": false
      }
    }
  }
}

Matching is exact and case-insensitive. One result is replaced with its ID; zero results return REFERENCE_NOT_FOUND; multiple results return matching options; and a bounded scan that cannot prove uniqueness returns an actionable error. See Human-readable references.

GraphQL Specs

A GraphQL schema says nothing about where it is served or how requests authenticate, so Spec.graphql carries both. Set it inside spec.graphql when creating a Project or through PATCH /specs/{spec_id} later. It is not part of stored Project or Target config. One-shot POST /generate still accepts the same object as config.graphql, because there is no persisted Spec resource in that flow.

{
  "graphql": {
    "endpoint": "https://api.parcel.example/graphql",
    "environments": [
      { "name": "sandbox", "url": "https://sandbox.api.parcel.example/graphql" },
      { "name": "production", "url": "https://api.parcel.example/graphql" }
    ],
    "auth": "basic",
    "scalars": {
      "DateTime": "string",
      "Money": "number",
      "JSONObject": "json"
    },
    "title": "Parcel"
  }
}

For Projects, edit GraphQL credential settings in Authentication. They remain part of the shared Spec.graphql API resource; changing them preserves endpoint, environment, and scalar settings.

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, basic_api_key for one API key sent as the Basic-auth username with an empty password, api_key with an explicit api_key_header, api_key_or_bearer for a key in api_key_header (use Authorization for a raw key) that also accepts OAuth access tokens as Authorization: Bearer, or none. Typeship does not invent a vendor-specific header name. This describes authentication in the generated client; it is separate from the write-only source.headers Typeship may need to fetch or introspect a protected source. scalars declares each custom scalar's real JSON representation: string, integer, number, boolean, or json. It overrides the defaults for well-known names such as DateTime, UUID, and JSON (see Generate from GraphQL). Other unmapped scalars stay untyped and warn; keys that match no scalar warn. title names the package and client (parcel, ParcelClient) and defaults to a name taken from the endpoint's host. error_types lists the object types that mean failure when an operation's union or interface result resolves to them; it replaces the default of every member whose name ends in Error, and an empty list turns the check off. Names that are not object types in the schema warn. page_size (1 to 1000, default 100) is the first a paginated connection call sends when the caller passes neither first nor last. 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.

Set docs_index_url when the llms.txt file lives somewhere other than <docs_url>/llms.txt. The generated CLI, MCP server, and agent guide use that URL verbatim and look for llms-full.txt beside it. Keep docs_url as the human-facing site URL; relative links from specification descriptions are resolved against it before generation.

Follow Connect your API guides to CLI and MCP to publish the index, configure its URLs, and verify search and reading end to end.

Update and inheritance behavior

On write, Project and Target config each replace that resource's whole stored object. Send every key you want kept, and null to clear that scope. At generation time, Typeship applies the Target override over the Project defaults, then adds the Spec's GraphQL settings. Read Project and Target configuration to see current settings; Generations do not expose a resolved configuration snapshot.

An empty retries.operations object contains no operation-specific overrides. Empty auth, cli, mcp, readme, and package objects inherit their Project fields because those groups merge by field. retries and pagination require objects; null is invalid for either group. To disable behavior, use retries.disabled: true or set a particular pagination rule to false.