--- title: "Connect your API guides to CLI and MCP" description: "Make your task guides searchable and readable from generated tools, then verify that an agent can find the right page." url: https://typeship.dev/docs/guides/connect-your-guides markdown: https://typeship.dev/docs/guides/connect-your-guides.md section: "Get started" --- > ## Documentation index > Fetch the documentation index at https://typeship.dev/llms.txt or every prose page and both generated references at https://typeship.dev/llms-full.txt. > Append .md to any prose docs URL, or send Accept: text/markdown, for the markdown twin of that page. # Connect your API guides to CLI and MCP Make your task guides searchable and readable from generated tools, then verify that an agent can find the right page. 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: ```md title="llms.txt" # Acme API ## Guides - [Create an upload](https://docs.acme.example/guides/create-an-upload.md): Reserve an upload, send the bytes, and confirm completion. ``` ```md title="llms-full.txt" # 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: ```json { "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: ```bash typeship projects retrieve ``` Add the documentation fields to the existing object, then save the complete object with `typeship projects update --config ''`. Saving config replaces that scope's stored object. Use a Target override when only one package should use a different site; see [Config](https://typeship.dev/docs/projects/config#stored-values-replace-effective-values-merge). Generate the updated packages: ```bash typeship projects generate ``` 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: ```bash 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: ```bash node dist/cli.js docs read https://docs.acme.example/guides/create-an-upload.md ``` In an MCP client, call: ```json {"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](https://typeship.dev/docs/guides/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 | Symptom | Check | | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Search finds only API operations | Verify the generated config points to the intended `llms.txt` and `llms-full.txt`, and that both return content without browser authentication. | | The guide is listed but its details are not searchable | Include its content in `llms-full.txt` and associate its title and URL using the format above. | | Search returns the wrong page | Use distinct page titles and descriptive index summaries. Check the page boundary and `Source:` URL in the full-text export. | | A read action fails | Fetch the returned URL directly. Keep it on the docs-site or index origin and serve Markdown without a login redirect. | | An update has not appeared | The CLI caches pages locally for one hour. Confirm the published files contain the update, allow the cache to expire, then repeat the same question. | | A fetch fails or returns no guide content | Each request has a 10-second deadline, a 2 MB body limit, and at most three redirects within its initial origin. Check size, latency, redirects, and content type. | 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. ## Sitemap [Documentation index](https://typeship.dev/llms.txt)