Skip to content
Handyverse documentation

Show interactive endpoint panels inside human guides. This preference is saved for future visits.

Choose an API
Shared guides · Developer resourcesView Markdown

Using the docs with agents

Give your agent the documentation for the APIs your integration uses. You can use downloadable Markdown and OpenAPI specs, or connect an MCP-capable client to the documentation service.

Start with the API overview

The API overview for agents explains which APIs to use and links to their agent instructions, specifications and update manifests. Read the instructions for every API your integration calls: credentials and identifiers have specific roles in each one.

For a substantial integration, consider generating an API client in your preferred language from the selected OpenAPI spec. Follow the guide for workflows and conditional requirements the generator may not enforce.

Connect through MCP

Model Context Protocol (MCP) lets your agent call documentation tools instead of reading an entire guide at once. Use Streamable HTTP and the address for the selected API on this site's host:

API MCP endpoint path
Handy REST API v3 /mcp/handy-rest-v3/
Channel API v1 /mcp/channel-v1/
Stream API v0 /mcp/stream-v0/
Hosting API v2 /mcp/hosting-v2/

No login, Application ID, Authentication Key, device connection key or LLM-provider key is required by these documentation endpoints. They run ordinary server code over published documentation and schemas. Your agent application supplies its own model and decides which tools to call.

Add the endpoint to your client's MCP settings. Replace YOUR_DOCS_HOST with the host serving this site; keep the trailing slash. Configuration formats vary by client, but a common JSON form is:

{
  "mcpServers": {
    "handy-rest-docs": {
      "url": "https://YOUR_DOCS_HOST/mcp/handy-rest-v3/"
    }
  }
}

You can download a configuration for this site, which includes the available API endpoints. Enable the entries your integration needs. The MCP service index lists their API identities and content revisions.

Ask focused questions

The documentation tools provide:

  • search: find guide sections and operations; filter by protocol or audience when useful.
  • fetch: read a complete section using an ID returned by search.
  • list_api_endpoints: discover methods, paths and operation identifiers.
  • get_operation: retrieve a method/path contract with authentication and referenced schemas.

For example, ask your agent to retrieve PUT /hamp/start with get_operation, then generate a request using that contract. The documentation service does not start HAMP or send device commands. Applications making real API requests still need the selected API's credentials and authorization to perform those actions.

Each API endpoint has its own documentation scope. Connect to the relevant endpoints when combining APIs; do not assume a Handy REST connection also supplies Channel or Stream contracts. Public documentation tools contain no internal verification records.

Versions and offline use

Tool replies identify the API, documentation source revision and content revision. Search-result IDs pin subsequent fetches to that content revision. Check these fields when comparing answers or fetching a previously found section.

If an older result is unavailable after a documentation release, search again to obtain the current section. Keep downloaded references when you need a lasting offline copy.

For file-based use, open an API's agent reference and select View Markdown, then obtain its OpenAPI spec. The agent download includes version information, an update link and checksums. Retain a verified copy for offline work. See the update instructions in that API's reference before replacing saved files.

The hosted MCP needs a network connection. A separately installed local MCP can use bundled documentation and a last-good cache; its online update source is independent of the agent's MCP connection. Downloading a JSON content snapshot alone does not install an MCP server.