MCP Request and Tool-call Examples

MCP clients normally handle initialization, protocol negotiation, tool discovery, and response parsing. The raw examples below are useful for diagnostics and client implementation tests.

Initialize

curl -X POST https://docs.thyris.ai/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-25",
      "capabilities": {},
      "clientInfo": {
        "name": "documentation-test-client",
        "version": "1.0.0"
      }
    }
  }'

The server negotiates the protocol version and reports the thyris-documentation server identity and tool capability. Clients should use the protocol version supported by their MCP SDK rather than hard-coding a version from this diagnostic example.

List Tools

curl -X POST https://docs.thyris.ai/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

The result contains the names, descriptions, JSON Schemas, and read-only annotations for all seven tools.

Resolve a Documentation Action

Use resolve_docs_action for a normal question or any other documentation-grounded request:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "resolve_docs_action",
    "arguments": {
      "action": "Explain how Merchant catalog webhooks work, when I should use them, and which security controls are required.",
      "section": "merchant-services",
      "maxDocuments": 5,
      "maxCharsPerDocument": 12000
    }
  }
}

The response contains the detected intent, selected sources, document content, related pages, public URLs, and synthesis instructions. The MCP client should use that evidence to produce the requested answer instead of exposing the raw tool response directly.

Build a Research Plan

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "research_docs",
    "arguments": {
      "goal": "Create a Merchant Services integration roadmap for this application",
      "codeContext": "Next.js storefront with product and checkout APIs, PostgreSQL product storage, and no inbound webhook route.",
      "section": "merchant-services",
      "maxDocuments": 8
    }
  }
}

The calling agent should inspect the code before constructing codeContext. The result is a reading plan, not the final roadmap.

Read the Research Sources

Use paths selected by research_docs:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "read_documents",
    "arguments": {
      "paths": [
        "merchant-services/01-merchant-readiness-checklist.md",
        "merchant-services/03-authentication-and-scopes.md",
        "merchant-services/04-catalog-data-model.md",
        "merchant-services/08-catalog-webhooks.md"
      ],
      "maxCharsPerDocument": 18000
    }
  }
}

Follow an Evidence Gap

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "find_related_docs",
    "arguments": {
      "path": "merchant-services/08-catalog-webhooks.md",
      "limit": 6
    }
  }
}

Call search_docs

JSON-RPC request:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "search_docs",
    "arguments": {
      "query": "catalog webhook x-webhook-secret validation",
      "limit": 3
    }
  }
}

curl:

curl -X POST https://docs.thyris.ai/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"search_docs","arguments":{"query":"catalog webhook x-webhook-secret validation","limit":3}}}'

Natural-language Codex request:

Use thyris_docs to find how the x-webhook-secret header should be validated for catalog webhooks. Read the most relevant document if the search excerpt is incomplete, and include the source URL.

Call get_document

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "get_document",
    "arguments": {
      "path": "merchant-services/03-authentication-and-scopes.md"
    }
  }
}

Natural-language Codex request:

Use the thyris_docs get_document tool to read merchant-services/03-authentication-and-scopes.md and summarize the available key scopes.

Call list_doc_sections

List one section:

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "list_doc_sections",
    "arguments": {
      "section": "thyris-ui"
    }
  }
}

Count and list all published documents:

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "list_doc_sections",
    "arguments": {}
  }
}

Natural-language Codex request:

Use the thyris_docs list_doc_sections tool with no section filter and report documentCount.

General AI Request Examples

The user does not need to choose search terms or know which document to open:

Use thyris_docs to answer this question: What is the difference between MCP and UCP in Thyris, and which one fits a read-only shopping assistant? Find and read the relevant sources, combine the evidence, and cite the documentation URLs.

Use thyris_docs to troubleshoot why a Merchant catalog webhook might return 401. Consider this context: the endpoint is public HTTPS and the request body is valid JSON. Read the relevant documentation before giving me a diagnostic checklist.

Use thyris_docs to summarize Merchant Services for a non-technical executive in five bullets. Ground every claim in the returned documentation.

Multi-tool Research Example

Ask a client to follow a complete retrieval flow:

Inspect my codebase first, then use only the thyris_docs MCP server for documentation research.

1. Call research_docs with my Merchant Services integration goal and concise facts from the code.
2. Read the proposed documents with read_documents.
3. Use find_related_docs only where prerequisites or operational details are missing.
4. Compare the documentation with the code and identify what already exists, what is missing, and what remains uncertain.
5. Produce a phased roadmap in dependency order.
6. Cite every documentation URL used and label your own recommendations separately.

Response Transport

Depending on content negotiation and the MCP client, responses can arrive as JSON or as Server-Sent Events:

event: message
data: {"result":{...},"jsonrpc":"2.0","id":3}

Clients should use an MCP SDK or parse the selected response mode correctly. A successful HTTP status alone does not prove the tool call succeeded; inspect the JSON-RPC result and any tool-level isError value.

HTTP Status Examples

Status	Meaning
200	MCP request accepted; inspect the JSON-RPC body for the operation result.
400	Malformed request, invalid JSON-RPC payload, or schema validation failure.
403	Host or browser origin rejected by endpoint validation.
404	The MCP endpoint path is incorrect or unavailable.
405	HTTP method is not valid for the attempted operation; a browser-style GET is not a tool call.
429	MCP request rate limit exceeded; honor Retry-After: 60.