AI tools reference

This page documents the MCP tool surface, the response envelope, export paths, JSON-RPC, the knowledge-graph.json schema, and troubleshooting. For setup, see How to connect AI tools to Quake AI docs. For a conceptual overview of what the server is and when to use each tool, see What the MCP server is and why to use it.

MCP tools#

The hosted MCP endpoint exposes nine callable tools. Cursor, Claude Desktop, and VS Code (with Copilot agent mode) can call them directly. Once configured, an IDE agent picks tools by intent. Describe what you want and the agent routes through the right tool. The reference below documents each tool's inputs, the response shape, and what to expect when nothing matches.

The endpoint requires no authentication. All tools read data only and back the public documentation surface. Rate limits apply per client IP.

search_docs#

Searches the Quake AI documentation corpus using BM25 plus knowledge graph traversal. Returns ranked pages with prerequisites, related operations, known issues, and workflow context.

Inputs:

Example prompt:

"Search the Quake AI docs for how to configure a floating IP in OpenTofu."

Returns: a doc_reference artifact whose content carries the full retrieval context (seedPages, prerequisites, relatedOperations) and whose markdown_preview renders the top result with prerequisites and related links wired as [[wikilinks]].

No matches: the markdown_preview says so and points the reader at https://docs.quake.ai.

get_template#

Returns a validated OpenTofu HCL or Heat HOT template for a requested service. The tool retrieves a curated template from the library; it does not synthesize new HCL.

Inputs:

Example prompt:

"Generate an OpenTofu template for a VM running Ubuntu 24.04 with 4 GB RAM, a security group allowing ports 22 and 80, and a floating IP."

Returns: an iac_template artifact whose content.templates[] carries every matching template and whose markdown_preview renders the primary template's HCL (capped after 20 lines, with a link to the canonical docs URL for the full source).

No matches: the response includes availableServices (services that have templates) and allTemplates (every known template id, title, and service set) so the agent can suggest a valid alternative without inventing one.

validate_launch_manifest#

Validates a quake.yaml manifest (as parsed JSON): schema rules, flavor alias resolution, and service type to IaC template mapping. Returns structured errors and warnings without emitting a handoff packet.

Inputs:

Example prompt:

"Validate this quake.yaml manifest before I prepare a preview launch."

Returns: a validation_status artifact whose content carries { valid, errors[], warnings[], resolved? } and whose markdown_preview lists error paths, warnings (including runtime: gpu), and resolved flavor or template paths when valid.

Invalid manifest: valid: false with actionable errors[] entries (field path plus message). Fix errors before calling prepare_launch.

See Launch handoff and the quake.yaml reference for field definitions.

prepare_launch#

Validates a manifest, then returns a downloadable launch handoff packet for a human or control-plane consumer. The platform validates intent only; it does not run builds or deploys.

Inputs:

Example prompt:

"Prepare a preview launch handoff for this quake.yaml on branch feature/login."

Returns: on success, a launch_handoff artifact whose JSON content includes request_id, action, manifest, resolved, evidence_bundle, and next_steps, plus a Markdown preview summarizing environment, flavor, templates, and manual next steps.

Invalid manifest: same { valid: false, errors[], warnings[] } shape as validate_launch_manifest with no handoff packet.

Action requirements: preview requires a preview environment entry; deploy, promote, and rollback require production. See Launch handoff for the branch workflow and evidence bundle stub.

export_okf#

Exports an Open Knowledge Format v0.1 knowledge sub-bundle for a Quake AI service or concept subtree: linked concept Markdown files plus an index.md for drop-in use in an Obsidian vault or any Markdown knowledge base. To save individual tool results to a notebook, see How to save Quake AI knowledge to Obsidian, Git, or Notion.

Inputs:

Provide exactly one of service or concept.

Example prompt:

"Export the Network service docs as an OKF bundle I can drop into my Obsidian vault."

Returns: a doc_reference artifact whose content carries { service, concept, link_style, root_node_id, root_label, files[], validation_passed, validation_issues[] }, where each file holds { relative_path, kind, content } (kind is concept, index, log, or root-index). The markdown_preview renders the bundle's primary index.md.

No selector: when neither service nor concept is provided, the response asks for one. An unknown or ambiguous slug returns a message naming the problem rather than an empty bundle.

get_migration_mapping#

Resolves a competitor provider, a Quake AI service or concept slug, or a competitor node id, then returns the curated competitor analogs that map onto Quake AI with their divergence notes.

Inputs:

Example prompt:

"Show how AWS networking maps onto Quake AI, with the divergences I should plan for."

Returns: a graph_query artifact whose content carries { query, resolvedAs, entries[] }. Each entry names the competitor term, its provider, the Quake AI concept or service it maps to, and any divergence notes. Provenance stays honest: a source URL and verification date appear only for human-verified records; every other entry reports as unverified. The markdown_preview lists each mapping with its divergences.

No matches: entries is empty and the preview suggests a provider (aws, gcp, azure), a service slug, or a concept slug.

get_workflow#

Returns the workflow ordering for a documentation page: its prerequisites, the pages that come before it, and the pages it leads to.

Inputs:

Example prompt:

"What should I read before and after the create-a-VM how-to?"

Returns: a graph_query artifact whose content carries { slug, pageId, title, requires[], before[], after[] }, where each list holds { id, label, url } steps. The markdown_preview renders three sections: Prerequisites, Comes after, and Leads to.

No match: when no page matches the slug, content is null and the preview says no page was found.

get_known_issues#

Returns the known error states for a Quake AI service, concept, or operation, plus the pages that resolve them.

Inputs:

Example prompt:

"What are the known issues with floating IPs, and which pages fix them?"

Returns: a graph_query artifact whose content carries { query, nodeId, entries[] }. Each entry is a known error state with its label and the resolution pages linked to it. The markdown_preview lists each issue with its resolution pages.

No matches: when no service, concept, or operation matches, nodeId is null; when a node matches but carries no recorded issues, entries is empty.

get_related#

Returns a knowledge-graph node's neighbors in any direction, optionally filtered to specific relation names.

Inputs:

Example prompt:

"Show everything connected to the Compute service in the knowledge graph."

Returns: a graph_query artifact whose content carries { nodeId, found, entries[] }. Each entry names the relation, the direction (out or in), and the neighbor's id, type, label, and URL. The markdown_preview groups neighbors by relation.

Edge cases: when no node has the id, found is false; when the relation filter matches nothing, entries is empty.

Response envelope#

Every MCP tool wraps its result in the same PortableArtifact envelope. The MCP transport emits the full envelope as structuredContent; the content[0].text field carries the rendered Markdown that clients display.

The markdown_preview is a copy of content[0].text. IaC code blocks longer than 20 lines truncate inline and append a pointer to the canonical docs URL, so the preview fits on screen and links to the source of truth rather than replacing it.

Example response from search_docs with query "floating IP":

{
  "artifact_type": "doc_reference",
  "title": "Search results for \"floating IP\"",
  "content": {
    "query": "floating IP",
    "results": {
      "seedPages": [
        {
          "title": "Allocate a floating IP",
          "slug": "network/how-to/allocate-floating-ip",
          "url": "/docs/network/how-to/allocate-floating-ip",
          "snippet": "Floating IPs map a public address onto a private port..."
        }
      ],
      "prerequisites": [{ "title": "Create a VPC" }],
      "relatedOperations": [{ "label": "Attach a floating IP" }]
    }
  },
  "metadata": {
    "generated_at": "2026-05-08T11:20:15.000Z",
    "quake_ai_docs_url": "https://docs.quake.ai/docs/network/how-to/allocate-floating-ip",
    "services_used": ["network"],
    "tags": ["docs", "quake-ai"],
    "source": "knowledge-graph"
  },
  "export": {
    "markdown_preview": "# Allocate a floating IP\n\nFloating IPs map a public address..."
  }
}

Calling the endpoint directly#

If you are not using an IDE client, call the endpoint as plain JSON-RPC.

• Endpoint: POST https://docs.quake.ai/api/mcp
• Transport: Streamable HTTP per the MCP specification. No session ID required.
• Auth: none.
• GET: returns 405 with a JSON-RPC error body. Use POST.

Example curl invocation of search_docs:

curl -sS https://docs.quake.ai/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_docs",
      "arguments": { "query": "floating IP" }
    }
  }'

The response carries the rendered Markdown in result.content[0].text and the full PortableArtifact envelope in result.structuredContent.

knowledge-graph.json schema#

The knowledge graph is a static JSON file regenerated at build time from MDX frontmatter and a competitor-divergences config. It is the structured layer behind on-site search, the MCP server's retrieval, the <SeeAlso> panel, prerequisite chains, and migration callouts.

Endpoint: https://docs.quake.ai/knowledge-graph.json

Top-level shape:

{
  "generated": "2026-05-23T13:42:00.000Z",
  "stats": { "nodes": 1136, "edges": 6538, "pages": 306, "services": 14, "concepts": 195, "competitors": 313, "templates": 15, "tools": 26 },
  "nodes": [ /* 1,136 nodes */ ],
  "edges": [ /* 6,538 edges */ ]
}

Node types#

Every node has at minimum { id, type, label }. Page nodes carry metadata.url, metadata.service, metadata.personas, metadata.competitor_analogs, metadata.difficulty, metadata.last_validated, and other frontmatter-derived fields. The full page prose is not embedded in the graph; it lives in a separate kg-text-index.json artifact that backs search.

Edge relations#

Every edge has { source, target, relation }. Some carry metadata (used for competitor diverges_from divergence lists) and provenance (source URL, last verified date).

Example node#

A real page node (truncated for length):

{
  "id": "page:network/concepts/floating-ips",
  "type": "page",
  "label": "Floating IPs",
  "url": "https://docs.quake.ai/docs/network/concepts/floating-ips",
  "metadata": {
    "content_type": "explanation",
    "service": "network",
    "personas": ["new_user", "devops_engineer", "developer", "architect"],
    "managed_service_status": "not_yet_available",
    "competitor_analogs": [
      "aws_elastic_ip", "azure_public_ip", "gcp_static_external_ip"
    ],
    "estimated_time": "8 minutes",
    "last_validated": "2026-05-19"
  }
}

Example edge (with divergence metadata)#

{
  "source": "concept:floating_ips",
  "target": "competitor:aws_elastic_ip",
  "relation": "diverges_from",
  "metadata": {
    "provider": "aws",
    "term": "Elastic IP addresses",
    "divergences": [
      "AWS charges idle EIPs.",
      "OpenStack floating IPs free/pool-limited.",
      "AWS regional instance/ENI.",
      "OpenStack project port."
    ],
    "confidence": "high",
    "doc_url": "https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html"
  }
}

Common queries#

Troubleshooting#

The MCP server does not appear in the IDE's tool list. Restart the IDE after editing its config file. Cursor reads .cursor/mcp.json at startup; Claude Desktop reads claude_desktop_config.json at startup; VS Code with Copilot agent mode reads .vscode/mcp.json. Confirm the file is valid JSON and the URL is reachable from the machine running the IDE.

search_docs returns no results. Try a broader query and prefer service vocabulary the docs use (for example floating IP, block volume, flavor). The corpus indexes published documentation only; private notes and internal wikis are not searchable here.

get_template returns a list of available services instead of HCL. No template matches the requested service or format. The response carries availableServices and allTemplates so the agent can pick a valid service and retry. If you expected a template to exist, check the automation templates index.

The agent generated content about the video platform "Quake AI" instead of Quake AI. Add the disambiguation rule to your system prompt or rules file. See How to connect AI tools to Quake AI docs.