Connect your API guides to CLI and MCP

Connect your documentation site so customers and agents can find task guidance alongside the generated API reference. The CLI's docs search and docs read commands and MCP's search_docs and read_docs tools use the same published guides.

You need a generated CLI or MCP Target, a public documentation site, and Markdown exports for its guides. For a saved Project, you also need permission to update its config and generate its Targets.

1. Publish an index and guide content

Your docs host may already publish these files. Check their contents before configuring Typeship:

• llms.txt: page titles, URLs, and short descriptions.
• llms-full.txt: guide content, with a title and canonical page URL for each page. Place it beside llms.txt.
• Individual guide URLs that return readable Markdown or plain text. The tools request text/markdown first.

For example, a documentation site at https://docs.acme.example could publish:

# Acme API

## Guides

- [Create an upload](https://docs.acme.example/guides/create-an-upload.md): Reserve an upload, send the bytes, and confirm completion.

# Create an upload

Source: https://docs.acme.example/guides/create-an-upload.md

Reserve an upload, send the bytes, and confirm completion.

## Prerequisites

Use a credential with permission to create and finish uploads. Have the file and its content type ready.

## Upload a file

Call createUpload to reserve an upload. Send the file bytes to the returned upload_url, then call finishUpload with the returned upload ID. Check that the upload reports a completed status before using it.

Replace this illustrative workflow with your API's actual operations and rules. Use absolute page URLs so an agent can read the exact result. The Source: line associates a page's sections with its URL. Linked page headings also work; a plain page title can be matched to its llms.txt entry.

An index without full text can expose page titles and descriptions in search. Publish full text when readers need to find details within a guide.

2. Configure the documentation URLs

Set docs_url to the human-facing site. Typeship defaults it to the Definition's externalDocs.url when present. Set docs_index_url only when the exact index is elsewhere:

{
  "docs_url": "https://docs.acme.example",
  "docs_index_url": "https://cdn.acme.example/agent/llms.txt"
}

With this config, Typeship reads the index URL verbatim and looks for full text at https://cdn.acme.example/agent/llms-full.txt. Guide URLs may use either the documentation site's origin or the index's origin.

For an existing Project, retrieve the current config first:

typeship projects retrieve <project_id>

Add the documentation fields to the existing object, then save the complete object with typeship projects update <project_id> --config '<complete-config-json>'. Saving config replaces that scope's stored object. Use a Target override when only one package should use a different site; see Config.

Generate the updated packages:

typeship projects generate <project_id>

For a one-off package, pass the config through typeship generate run --config. To try your site with an already-generated CLI, use acme config set docs-url https://docs.acme.example. This local override uses the new site's conventional llms.txt and overrides an embedded docs_index_url. Run acme config unset docs-url to return to the URLs embedded at generation.

3. Test a question your customers ask

Build the generated CLI and search for a task:

node dist/cli.js docs search "upload a file" --json

Find the intended guide in the result. Check that it has a useful excerpt, the correct page URL, and a read_command. The read command uses the installed CLI's name. For an unpublished local package, keep the node dist/cli.js prefix and use the returned URL:

node dist/cli.js docs read https://docs.acme.example/guides/create-an-upload.md

In an MCP client, call:

{"name":"search_docs","arguments":{"query":"upload a file"}}

Use the returned read_tool arguments to call read_docs for that guide. Check that its steps include the prerequisites, required operation order, expected result, and recovery from a failed step. See Connect a generated MCP server for client setup.

The integration is ready when both search surfaces find the intended page and their read action retrieves the complete guide. A generated operation reference alone does not verify that your external guides are connected.

Write guides that answer tasks

Keep wire-level fields and schemas in the API reference. Use guides to explain the decisions a developer must make to complete a task:

• State prerequisites: credentials and scopes, environment, existing resources, and inputs.
• Name operations in the order they run, including which output becomes the next input.
• Explain business rules the schema cannot express, such as expiration, asynchronous completion, or retry safety.
• Include a working example, a successful result, and recovery for likely failures.
• Give each page a descriptive title, stable URL, and index summary using the words customers search for.

If the site uses diagrams, cards, or tabs, check the Markdown export too. Include the instructions those components convey; raw component tags do not tell an agent what to do.

Diagnose missing or stale guides

Documentation fetches happen when a docs command or tool runs. Updating guide content at the same URLs does not require regenerating the package. Changes to the embedded documentation URLs do.