Astro Docs MCP Server

https://github.com/withastro/docs-mcp
Admin
The Astro Docs MCP Server provides AI tools like Cursor, VS Code, and Claude with structured access...
Tokens:17,913
Snippets:113
Trust Score:8.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Astro Docs MCP server in Cursor via deep link

Source: https://github.com/withastro/docs-mcp/blob/main/README.md

Open this deep link in your browser to install the Astro Docs MCP server in Cursor. GitHub does not support Cursor deep links, so the link must be opened manually.

```text
cursor://anysphere.cursor-deeplink/mcp/install?name=Astro%20docs&config=eyJ1cmwiOiJodHRwczovL21jcC5kb2NzLmFzdHJvLmJ1aWxkL21jcCJ9
```

--------------------------------

### Install Astro Docs MCP server in VS Code via deep link

Source: https://github.com/withastro/docs-mcp/blob/main/README.md

Open this deep link in your browser to install the Astro Docs MCP server in VS Code. GitHub does not support VS Code deep links, so the link must be opened manually.

```text
vscode:mcp/install?%7B%22name%22%3A%22Astro%20docs%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.docs.astro.build%2Fmcp%22%7D
```

--------------------------------

### Error handling: GET request and backend failure

Source: https://github.com/withastro/docs-mcp/blob/main/_autodocs/api-reference/handler.md

Shows that GET requests are rejected with HTTP 405 before any MCP work, and that when the Kapa API is unavailable, the tool returns an error text block but the handler still completes with HTTP 200.

```sh
# GET requests are rejected by the handler before any MCP work
curl -i "https://mcp.docs.astro.build/mcp"
# HTTP/1.1 405 Method Not Allowed
# Allow: POST
# Method Not Allowed

# When the Kapa API is unavailable, the tool returns an error text block
# instead of throwing; the handler still completes with HTTP 200:
curl -sS -X POST "https://mcp.docs.astro.build/mcp" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 3, "method": "tools/call",
    "params": { "name": "search_astro_docs", "arguments": { "query": "actions" } }
  }'
# { "jsonrpc": "2.0", "id": 3,
#   "result": { "content": [ { "type": "text", "text": "{\n  \"error\": \"Error: Unable to fetch data from API. Please try again later.\"\n}" } ] } }
```

--------------------------------

### initialize success response

Source: https://github.com/withastro/docs-mcp/blob/main/_autodocs/endpoints.md

Example of a successful `initialize` response from the MCP endpoint. The server returns its name, version, and logging capability. The protocol version is negotiated between client and server.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "<negotiated version>",
    "capabilities": { "logging": {} },
    "serverInfo": { "name": "Astro Docs server", "version": "1.0.0" }
  }
}
```

--------------------------------

### GET /mcp

Source: https://github.com/withastro/docs-mcp/blob/main/_autodocs/endpoints.md

The GET method on /mcp is explicitly rejected by the handler, returning a 405 Method Not Allowed.

```APIDOC
## GET /mcp

### Description
Explicitly rejected by the handler. This endpoint is not supported and returns a 405 Method Not Allowed.

### Method
GET

### Endpoint
/mcp

### Response
#### Error Response (405)
- Method Not Allowed (none) - The GET method is not allowed on this endpoint.
```

--------------------------------

### Verify routing with curl

Source: https://github.com/withastro/docs-mcp/blob/main/_autodocs/api-reference/config.md

Sends a GET request to the MCP endpoint and shows the first 8 lines of the response. A 405 status proves the function handled the request, not a static asset.

```Shell
curl -i https://mcp.docs.astro.build/mcp | head -8
```

--------------------------------

### curl GET /mcp showing 405 rejection

Source: https://github.com/withastro/docs-mcp/blob/main/_autodocs/endpoints.md

Use this curl command to verify that GET requests to the MCP endpoint are rejected with a 405 Method Not Allowed status, including the Allow: POST header and the plain text body.

```sh
curl -i https://mcp.docs.astro.build/mcp
# HTTP/1.1 405 Method Not Allowed
# Allow: POST
# Content-Type: text/plain
#
# Method Not Allowed
```

--------------------------------

### tools/call error response for falsy query

Source: https://github.com/withastro/docs-mcp/blob/main/_autodocs/endpoints.md

Example of a JSON-RPC error response when `tools/call` is invoked with a falsy `query`. The tool throws `Error("Query is required")`, and the SDK returns `-32603` (InternalError).

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "error": { "code": -32603, "message": "Query is required" }
}
```

--------------------------------

### tools/call success response

Source: https://github.com/withastro/docs-mcp/blob/main/_autodocs/endpoints.md

Example of a successful `tools/call` response. The result contains a text block with the search results as a JSON string. The `text` field is produced by `JSON.stringify(searchResult, null, 2)`.

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      { "type": "text", "text": "{\n  \"search_results\": [...]\n}" }
    ]
  }
}
```

--------------------------------

### handler default export for Netlify Edge Function

Source: https://github.com/withastro/docs-mcp/blob/main/_autodocs/api-reference/handler.md

Default export of the Netlify Edge Function handler. It rejects GET requests with a 405 response, adapts the Web API Request to Node HTTP via toReqRes, connects a stateless StreamableHTTPServerTransport, handles the request, and converts the Node response back to a Web API Response. On error, it logs and returns a 500 JSON response.

```ts
// Netlify Edge Function Handler
export default async function handler(req: Request) {
  if (req.method === "GET") {
    return new Response("Method Not Allowed", {
      status: 405,
      headers: {
        "Content-Type": "text/plain",
        Allow: "POST",
      },
    });
  }
  try {
    const { req: nodeReq, res: nodeRes } = toReqRes(req);
    const server = getServer();
    const transport = new StreamableHTTPServerTransport({
      sessionIdGenerator: undefined, // Stateless mode
    });
    await server.connect(transport);

    // Parse request body as JSON
    const body = await req.json();

    // Handle the request through the transport
    await transport.handleRequest(nodeReq, nodeRes, body);

    // Handle response closing
    nodeRes.on("close", () => {
      transport.close();
      server.close();
    });

    // Convert Node.js ServerResponse back to Web API Response
    return toFetchResponse(nodeRes);
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : String(error);
    console.error("Error in MCP server:", errorMessage);
    return Response.json(formatResponse({ error: errorMessage }), {
      status: 500,
    });
  }
}
```

--------------------------------

### Handle MCP tool errors with JSON-RPC error channel and parsed JSON error in TypeScript pseudo-code

Source: https://github.com/withastro/docs-mcp/blob/main/_autodocs/errors.md

Use this MCP client pseudo-code to process the response from search_astro_docs. It checks res.isError for JSON-RPC errors like 'Query is required', and parses the text if it starts with '{' to detect Kapa backend failures such as 'Unable to fetch data from API'. The snippet shows the expected output and how to handle each failure mode.

```TypeScript
// MCP client pseudo-code (SDK-side)
const res = await client.callTool({ name: "search_astro_docs", arguments: { query } });
if (res.isError) {
  // JSON-RPC error channel: e.g. "Query is required"
  // Retry with a non-empty query; if persistent, treat as server-side fault.
} else {
  const text = res.content[0].text;
  if (text.startsWith("{")) {
    const parsed = JSON.parse(text);
    if (parsed.error) {
      // Kapa backend unavailable — retry later ("Unable to fetch data from API").
    }
  }
}
```

--------------------------------

### getServer() factory for McpServer with search_astro_docs tool

Source: https://github.com/withastro/docs-mcp/blob/main/_autodocs/api-reference/internals.md

Factory that constructs a fully configured McpServer instance per call, invoked once per HTTP request by handler. Registers the search_astro_docs tool with a zod inputSchema and a callback that throws Error("Query is required") on falsy query, otherwise calls sendKapaRequest and formats the result.

```ts
function getServer(): McpServer {
  const server = new McpServer(
    {
      name: "Astro Docs server",
      version: "1.0.0",
    },
    {
      capabilities: {
        logging: {},
      },
    }
  );

  server.registerTool(
    "search_astro_docs",
    {
      title: "Search Astro Docs",
      description: "Search the official Astro framework docs",
      inputSchema: { query: z.string().describe("Search query") },
    },
    async ({ query }) => {
      if (!query) {
        throw new Error("Query is required");
      }
      const result = await sendKapaRequest<SearchResponse>("search", query);
      return formatResponse(result);
    }
  );
  return server;
}
```

--------------------------------

### netlify.toml - Netlify build configuration

Source: https://github.com/withastro/docs-mcp/blob/main/_autodocs/configuration.md

Publishes the 'public' directory, which contains the static landing page 'public/index.html'. This page displays the client configuration: Name: Astro Docs, URL: https://mcp.docs.astro.build/mcp, Transport: http.

```toml
[build]
publish = "public"
```

--------------------------------

### Initialize MCP endpoint with curl

Source: https://github.com/withastro/docs-mcp/blob/main/_autodocs/api-reference/handler.md

Sends a JSON-RPC initialize request to the MCP endpoint. The handler converts this to Node request/response via toReqRes and returns serverInfo with name 'Astro Docs server' and version '1.0.0'.

```sh
curl -sS -X POST "https://mcp.docs.astro.build/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "example-client", "version": "0.1.0" }
    }
  }'
```

--------------------------------

### Setting environment variables with Netlify CLI

Source: https://github.com/withastro/docs-mcp/blob/main/_autodocs/configuration.md

Commands to set the three required environment variables using the Netlify CLI. Each variable must be set before the module loads, as it throws at evaluation time if any is missing or falsy.

```sh
netlify env:set KAPA_API_KEY <value>
netlify env:set KAPA_PROJECT_ID <value>
netlify env:set KAPA_INTEGRATION_ID <value>
```

--------------------------------

### Configure Astro Docs MCP server for Windsurf with local proxy

Source: https://github.com/withastro/docs-mcp/blob/main/README.md

Use this configuration in Windsurf to run the Astro Docs MCP server through a local proxy. As of July 2025, Windsurf does not support streamable HTTP MCP servers, so this proxy is required.

```json
{
  "mcpServers": {
    "Astro docs": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.docs.astro.build/mcp"]
    }
  }
}
```

--------------------------------

### package.json - Metadata only

Source: https://github.com/withastro/docs-mcp/blob/main/_autodocs/configuration.md

Defines package metadata for the project. The 'main' field is vestigial; index.js does not exist and nothing is published from Node, as deployment runs entirely through Netlify Edge Functions.

```json
{
  "name": "docs-mcp",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
  "packageManager": "pnpm@9.15.6+sha512...",
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.15.1",
    "@netlify/edge-functions": "^2.15.6",
    "fetch-to-node": "^2.1.0",
    "zod": "^3.25.76"
  }
}
```

--------------------------------

### deno.json - Deno import map

Source: https://github.com/withastro/docs-mcp/blob/main/_autodocs/configuration.md

Defines the Deno import map for runtime dependency resolution. Maps aliases to npm packages, including @modelcontextprotocol/sdk, fetch-to-node, @netlify/edge-functions, and astro. The lock file deno.lock pins the resolved graph, e.g., @modelcontextprotocol/sdk@1.15.1.

```json
{
  "imports": {
    "fetch-to-node": "npm:fetch-to-node@2",
    "astro": "npm:astro",
    "@modelcontextprotocol/sdk": "npm:@modelcontextprotocol/sdk@1.15.1",
    "@netlify/edge-functions": "npm:@netlify/edge-functions"
  }
}
```

--------------------------------

### Architecture and data flow diagram

Source: https://github.com/withastro/docs-mcp/blob/main/_autodocs/api-reference/mcp-server.md

Text diagram showing the request flow from the Netlify Edge runtime through the handler, MCP server, transport, and Kapa AI API, including error handling and response closure.

```text
Netlify Edge runtime
  │  POST /mcp  (Web API Request)
  ▼
handler(req)                         [lines 98–137]
  │  GET → 405 "Method Not Allowed"  [lines 99–107]
  │  toReqRes(req)  → { req: IncomingMessage, res: ServerResponse }   [line 109]
  │  getServer()    → new McpServer(...) with tool search_astro_docs   [line 110]
  │  new StreamableHTTPServerTransport({ sessionIdGenerator: undefined })  [lines 111–113]
  │  server.connect(transport)                                           [line 114]
  │  transport.handleRequest(nodeReq, nodeRes, body)                     [line 120]
  ▼
Kapa AI query API
  X-API-KEY: KAPA_API_KEY  |  body { query, integration_id }
  POST https://api.kapa.ai/query/v1/projects/{projectId}/search/
  ▼
JSON result → formatResponse() → JSON.stringify(data, null, 2) → text content
  ▼
nodeRes "close" → transport.close(); server.close()   [lines 123–126]
  ▼
toFetchResponse(nodeRes) → Web API Response          [line 129]
```

--------------------------------

### Request and response lifecycle flow

Source: https://github.com/withastro/docs-mcp/blob/main/_autodocs/types.md

A text-based diagram illustrating the transformation of requests and responses through the MCP server and Kapa API integration.

```text
Request (Web API)
  → ReqRes ({ req: IncomingMessage, res: ServerResponse })          [toReqRes]
  → transport.handleRequest(req, res, parsedBody: unknown)          [SDK, parses req.json()]
  → McpServer dispatches "tools/call" for search_astro_docs
  → sendKapaRequest<SearchResponse>("search", query)
        → Promise<SearchResponse | { error: string }>
  → formatResponse(...) → { content: [{ type: "text", text: string }] }
        (validated by SDK as CallToolResult)
  → toFetchResponse(res) → Response (Web API)
```

--------------------------------

### Add Astro Docs MCP server to Claude Code

Source: https://github.com/withastro/docs-mcp/blob/main/README.md

Run this command in your terminal to add the Astro Docs MCP server to Claude Code using the streamable HTTP transport.

```sh
claude mcp add --transport http "Astro docs" https://mcp.docs.astro.build/mcp
```

--------------------------------

### Config interface from @netlify/edge-functions

Source: https://github.com/withastro/docs-mcp/blob/main/_autodocs/types.md

Defines the structure for the exported config constant, including caching, path exclusions, and HTTP method constraints.

```ts
type Cache = 'off' | 'manual';
type Path = `/${string}`;
type OnError = 'fail' | 'bypass' | Path;
type HTTPMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS';

interface Config {
    cache?: Cache;
    excludedPath?: Path | Path[];
    excludedPattern?: string | string[];
    onError?: OnError;
    path?: Path | Path[];
    pattern?: string | string[];
    method?: HTTPMethod | HTTPMethod[];
    rateLimit?: RateLimitConfig; // { action?, aggregateBy?, to?, windowSize }
}
```

--------------------------------

### POST /mcp

Source: https://github.com/withastro/docs-mcp/blob/main/_autodocs/endpoints.md

Documentation for the MCP streamable HTTP endpoint, including request headers, JSON-RPC methods, response schemas, and status codes.

```APIDOC
## POST /mcp

### Description
This is the MCP streamable HTTP endpoint for the Astro Docs MCP server. It accepts JSON-RPC 2.0 messages and handles MCP protocol methods such as initialize, tools/list, and tools/call.

### Method
POST

### Endpoint
/mcp

### Parameters
#### Headers
- **Content-Type** (string) - Required - Must be `application/json` for JSON-RPC messages.
- **Accept** (string) - Recommended - `application/json, text/event-stream` to enable SSE streaming.
- **Mcp-Session-Id** (string) - Optional - Not required; the server runs in stateless mode.

#### Request Body
- **jsonrpc** (string) - Required - Must be `"2.0"`.
- **method** (string) - Required - The JSON-RPC method to invoke (e.g., `initialize`, `tools/list`, `tools/call`).
- **id** (number) - Required for requests - The request identifier.
- **params** (object) - Optional - Method-specific parameters.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": { "name": "example-client", "version": "1.0.0" }
  }
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - Always `"2.0"`.
- **id** (number) - The request identifier.
- **result** (object) - The method-specific result.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "logging": {} },
    "serverInfo": { "name": "Astro Docs server", "version": "1.0.0" }
  }
}
```

### Error Handling
- **400** - Invalid JSON-RPC (parse error or invalid request), or a batch containing multiple messages with `initialize`.
- **405** - Non-POST request to this route.
- **500** - Transport-level throw caught by the handler.
- **-32601** - Method not found.
- **-32603** - Internal error (e.g., when `query` is falsy in `tools/call`).
```

--------------------------------

### Type definition of Config from @netlify/edge-functions

Source: https://github.com/withastro/docs-mcp/blob/main/_autodocs/api-reference/config.md

Exact type definition of `Config` from `@netlify/edge-functions@2.15.6`. Shows available properties like `cache`, `excludedPath`, `onError`, `path`, `pattern`, `method`, and `rateLimit`.

```TypeScript
type Cache = 'off' | 'manual';
type Path = `/${string}`;
type OnError = 'fail' | 'bypass' | Path;
type HTTPMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS';

interface Config {
    cache?: Cache;                        // 'off' | 'manual'
    excludedPath?: Path | Path[];
    excludedPattern?: string | string[];
    onError?: OnError;                    // 'fail' | 'bypass' | Path
    path?: Path | Path[];
    pattern?: string | string[];
    method?: HTTPMethod | HTTPMethod[];
    rateLimit?: RateLimitConfig;          // { action?, aggregateBy?, to?, windowSize }
}
```

--------------------------------

### Call search_astro_docs tool with curl

Source: https://github.com/withastro/docs-mcp/blob/main/_autodocs/api-reference/handler.md

Invokes the search_astro_docs tool with a query. The response contains pretty-printed Kapa search results in result.content[0].text.

```sh
curl -sS -X POST "https://mcp.docs.astro.build/mcp" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": { "name": "search_astro_docs", "arguments": { "query": "astro add" } }
  }'
```

--------------------------------

### sendKapaRequest() function implementation

Source: https://github.com/withastro/docs-mcp/blob/main/_autodocs/api-reference/internals.md

Async function that sends a POST request to the Kapa API endpoint. It constructs the URL from the project ID and action, includes the API key in headers, and sends the query and integration ID in the JSON body. On non-OK responses, it logs the error text and returns a fixed error object; otherwise it returns the parsed JSON.

```typescript
async function sendKapaRequest<T = unknown>(
  action: string,
  query: string
): Promise<T | { error: string }> {
  const url = `https://api.kapa.ai/query/v1/projects/${projectId}/${action}/`;

  const response = await fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-KEY": apiKey!,
    },
    body: JSON.stringify({
      query,
      integration_id: integrationId,
    }),
  });
  if (!response.ok) {
    const errorText = await response.text();
    console.error(`Kapa API error: ${errorText}`);
    return {
      error: "Error: Unable to fetch data from API. Please try again later.",
    };
  }
  return await response.json();
}
```

--------------------------------

### Module-level environment variable validation

Source: https://github.com/withastro/docs-mcp/blob/main/_autodocs/api-reference/mcp-server.md

Reads three required environment variables from Netlify.env and throws an error at module load if any are missing. This prevents the Edge Function from booting if configuration is incomplete.

```typescript
const apiKey = Netlify.env.get("KAPA_API_KEY");
const projectId = Netlify.env.get("KAPA_PROJECT_ID");
const integrationId = Netlify.env.get("KAPA_INTEGRATION_ID");

if (!apiKey || !projectId || !integrationId) {
  throw new Error(
    "Missing required environment variables: KAPA_API_KEY, KAPA_PROJECT_ID, or KAPA_INTEGRATION_ID"
  );
}
```

--------------------------------

### Restrict config to POST only

Source: https://github.com/withastro/docs-mcp/blob/main/_autodocs/api-reference/config.md

Alternative configuration that restricts the function to POST only. With this, Netlify itself answers non-POST requests with its own 405 instead of the handler's explicit response.

```TypeScript
export const config: Config = {
  path: ["/mcp"],
  method: ["POST"],
};
```

--------------------------------

### POST /mcp

Source: https://github.com/withastro/docs-mcp/blob/main/_autodocs/endpoints.md

The MCP streamable-HTTP endpoint that accepts JSON-RPC messages. This is the only HTTP route exposed by the project.

```APIDOC
## POST /mcp

### Description
Accepts JSON-RPC messages for the MCP streamable-HTTP endpoint. This is the primary entry point for MCP clients to interact with the server.

### Method
POST

### Endpoint
/mcp

### Parameters
#### Request Body
- JSON-RPC message (object) - Required - A JSON-RPC 2.0 request, notification, or response object.

### Response
#### Success Response (200)
- JSON-RPC response object (object) - The response to the JSON-RPC request.

#### Success Response (202)
- JSON-RPC response object (object) - Accepted for processing; may be used for asynchronous operations.

#### Error Response (400)
- Error object (object) - Invalid JSON-RPC request or malformed message.

#### Error Response (500)
- Error object (object) - Internal server error.

### Response Example
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {}
}
```

--------------------------------

### sendKapaRequest<T>(action, query)

Source: https://github.com/withastro/docs-mcp/blob/main/_autodocs/api-reference/internals.md

Sends a POST request to the Kapa API endpoint for a given action and query. Returns the parsed JSON response or an error object if the request fails.

```APIDOC
## sendKapaRequest<T>(action, query)

### Description
Sends a POST request to the Kapa API endpoint for a given action and query. Returns the parsed JSON response or an error object if the request fails.

### Method
POST

### Endpoint
`https://api.kapa.ai/query/v1/projects/${projectId}/${action}/`

### Parameters
#### Path Parameters
- **projectId** (string) - Required - The project ID from environment variables.
- **action** (string) - Required - The Kapa endpoint segment appended to the base URL. Called only with `"search"`.

#### Request Body
- **query** (string) - Required - The user's search text.
- **integration_id** (string) - Required - The integration ID from environment variables.

### Request Example
```json
{
  "query": "example search text",
  "integration_id": "your-integration-id"
}
```

### Response
#### Success Response (200)
- **T** (unknown) - The parsed JSON body when the response is OK.

#### Error Response (non-OK)
- **error** (string) - A fixed error message when the Kapa API returns a non-OK status.

### Response Example
```json
{
  "error": "Error: Unable to fetch data from API. Please try again later."
}
```

### Headers
- **Content-Type**: application/json
- **X-API-KEY**: ${apiKey} (from KAPA_API_KEY environment variable)
```

--------------------------------

### ReqRes, toReqRes, and toFetchResponse types from fetch-to-node

Source: https://github.com/withastro/docs-mcp/blob/main/_autodocs/types.md

Type definitions and utility functions used for converting between Fetch API requests/responses and Node.js IncomingMessage/ServerResponse objects.

```ts
export type ReqRes = { req: IncomingMessage; res: ServerResponse };
export declare function toReqRes(req: Request, options?: ToReqResOptions): ReqRes;
export declare function toFetchResponse(res: ServerResponse): Promise<Response>;
```

--------------------------------

### Detect Kapa backend soft failure in MCP client

Source: https://github.com/withastro/docs-mcp/blob/main/_autodocs/errors.md

Inspects the tool result's text content for the literal "error" key because the Kapa non-OK response is not surfaced as a JSON-RPC error. The server returns a successful CallToolResult with the error object as text, so clients must check text rather than error channel.

```typescript
const text = result.content?.[0]?.text ?? "";
if (text.includes('"error"')) { /* Kapa was unavailable */ }
```
Tokens:
Raw