> For the complete documentation index, see [llms.txt](https://k-ai.gitbook.io/knowledge-ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://k-ai.gitbook.io/knowledge-ai/k-ai-mcp/retrieval-tools.md).

# Retrieval tools (stable)

Server: `https://api-retrieval.kai-studio.ai/mcp`. **Status: stable.** Seven tools that expose K-AI knowledge primitives to MCP clients. Each tool maps one-to-one to a REST operation on the K-AI Retrieval API; the K-AI MCP server forwards calls under the credential the host presented — an [OAuth 2.1](/knowledge-ai/k-ai-mcp/oauth-flow.md) Bearer token, or an [Organization API key](/knowledge-ai/k-ai-mcp/autonomous-agents.md) for unattended agents.

Every response is wrapped as `{"response": <payload>}`. Identifiers are prefixed (`ki_` for K-AI instances, `kd_` for documents, `kn_` for semantic nodes, `kc_` for document chunks) and must be passed back as-is — the server validates the exact prefix and rejects anything else with HTTP 400.

## Tools overview

| operationId                                    | Purpose                                                                                                                  | Underlying REST endpoint                             |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------- |
| `retrieval_instances_list_available_instances` | Discover the K-AI instances the user can access, their relationships, and the user's persona context.                    | `POST /retrieval/instances/list-available-instances` |
| `retrieval_documents_list`                     | Paginate through every document of a K-AI instance.                                                                      | `POST /retrieval/documents/list`                     |
| `retrieval_documents_get_document`             | Fetch the metadata, summary and source URL of a single document.                                                         | `POST /retrieval/documents/get-document`             |
| `retrieval_documents_list_by_ids`              | Batch-fetch the metadata, summary and source URL of several documents in one call.                                       | `POST /retrieval/documents/list-by-ids`              |
| `retrieval_semantic_nodes_search`              | Semantic search inside a K-AI instance; returns semantic nodes and the best-matching excerpts of the retained documents. | `POST /retrieval/semantic-nodes/search`              |
| `retrieval_documents_expand_chunk`             | Read the chunks immediately before and after an excerpt returned by a search.                                            | `POST /retrieval/documents/expand-chunk`             |
| `retrieval_documents_get_chunks`               | Read a whole document, page by page, in reading order.                                                                   | `POST /retrieval/documents/chunks`                   |

The canonical call order is: `retrieval_instances_list_available_instances` -> `retrieval_semantic_nodes_search` on the chosen instance(s) -> `retrieval_documents_list_by_ids` for the source URLs of the cited documents. When an excerpt is too short to answer, `retrieval_documents_expand_chunk` reads its surroundings; when a document must be read in full, `retrieval_documents_get_chunks` pages through it. `retrieval_documents_list` and `retrieval_documents_get_document` are auxiliary surfaces for browsing.

## retrieval\_instances\_list\_available\_instances

Returns the K-AI instances the authenticated user can access (with names and descriptions), the admin-defined relationships between those instances (natural-language descriptions of specialisation, scope override, complementarity, language or geography scoping, deprecation, etc.), and the persona context derived from the user's groups. Call this first to get the full picture, then route subsequent searches based on the relationship hints. When the relationships indicate overlap or specialisation, issue parallel searches across the relevant instances in the same turn.

The caller is identified by the access token, the [Organization API key](/knowledge-ai/authentication/organization-api-keys.md) presented as a Bearer credential, or the cookie; no request body fields are required.

### Input schema

| Field    | Type | Required | Description        |
| -------- | ---- | -------- | ------------------ |
| *(none)* | —    | —        | Empty object `{}`. |

### Output schema

| Field                                  | Type                | Description                                                                                                                                                                                                                                                                                       |
| -------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `response.persona`                     | string \| null      | Composed persona text built from the user's groups. Acts as a lens on tone and emphasis; it does NOT filter which instances are searchable.                                                                                                                                                       |
| `response.instances`                   | array               | Accessible K-AI instances.                                                                                                                                                                                                                                                                        |
| `response.instances[].id`              | string (`ki_*`)     | K-AI instance identifier.                                                                                                                                                                                                                                                                         |
| `response.instances[].name`            | string              | Display name.                                                                                                                                                                                                                                                                                     |
| `response.instances[].description`     | string \| null      | Free-form description of the instance content.                                                                                                                                                                                                                                                    |
| `response.instances[].organization_id` | string \| null      | Owning organisation identifier.                                                                                                                                                                                                                                                                   |
| `response.relationships`               | array               | Admin-defined links between accessible instances.                                                                                                                                                                                                                                                 |
| `response.relationships[].between`     | array\[2] of string | Pair of `ki_*` ids the relationship connects.                                                                                                                                                                                                                                                     |
| `response.relationships[].description` | string              | Natural-language description of the relationship.                                                                                                                                                                                                                                                 |
| `response.notice`                      | string              | Present **only** when `instances` is empty: plain-language explanation that this identity reaches no knowledge base because it has not been added to a retrieval group yet. Relay it and stop — the tool takes no arguments, so there is no other query to try and no instance id may be guessed. |

### Example

{% tabs %}
{% tab title="Python (MCP SDK)" %}

```python
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    url = "https://api-retrieval.kai-studio.ai/mcp"
    headers = {"Authorization": "Bearer YOUR_TOKEN"}
    async with streamablehttp_client(url, headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool(
                "retrieval_instances_list_available_instances", {}
            )
            print(result.structuredContent)

asyncio.run(main())
```

{% endtab %}

{% tab title="TypeScript (MCP SDK)" %}

```ts
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://api-retrieval.kai-studio.ai/mcp"),
  { requestInit: { headers: { Authorization: "Bearer YOUR_TOKEN" } } }
);
const client = new Client({ name: "demo", version: "1.0.0" });
await client.connect(transport);
const result = await client.callTool({
  name: "retrieval_instances_list_available_instances",
  arguments: {},
});
console.log(result.structuredContent);
```

{% endtab %}

{% tab title="Raw HTTP" %}

```bash
curl -X POST https://api-retrieval.kai-studio.ai/retrieval/instances/list-available-instances \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

{% endtab %}
{% endtabs %}

## retrieval\_documents\_list

Returns a paginated list of all documents in a K-AI instance. Use after a semantic search to explore additional content from the same instance, or for catalog-style browsing when the user does not have a specific query.

### Input schema

| Field         | Type               | Required | Description                                                                     |
| ------------- | ------------------ | -------- | ------------------------------------------------------------------------------- |
| `instance_id` | string (`ki_*`)    | yes      | K-AI instance identifier (from `retrieval_instances_list_available_instances`). |
| `offset`      | integer (0–100000) | yes      | Number of documents to skip.                                                    |
| `limit`       | integer (1–1000)   | yes      | Maximum number of documents to return.                                          |

### Output schema

| Field             | Type            | Description                                                     |
| ----------------- | --------------- | --------------------------------------------------------------- |
| `response`        | array           | Document objects.                                               |
| `response[].id`   | string (`kd_*`) | K-AI document identifier.                                       |
| `response[].name` | string          | Document name (filename or extracted title).                    |
| `response[].*`    | any             | Additional metadata fields depending on instance configuration. |

### Example

{% tabs %}
{% tab title="Python (MCP SDK)" %}

```python
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    url = "https://api-retrieval.kai-studio.ai/mcp"
    headers = {"Authorization": "Bearer YOUR_TOKEN"}
    async with streamablehttp_client(url, headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool(
                "retrieval_documents_list",
                {"instance_id": "ki_abc123", "offset": 0, "limit": 50},
            )
            print(result.structuredContent)

asyncio.run(main())
```

{% endtab %}

{% tab title="TypeScript (MCP SDK)" %}

```ts
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://api-retrieval.kai-studio.ai/mcp"),
  { requestInit: { headers: { Authorization: "Bearer YOUR_TOKEN" } } }
);
const client = new Client({ name: "demo", version: "1.0.0" });
await client.connect(transport);
const result = await client.callTool({
  name: "retrieval_documents_list",
  arguments: { instance_id: "ki_abc123", offset: 0, limit: 50 },
});
console.log(result.structuredContent);
```

{% endtab %}

{% tab title="Raw HTTP" %}

```bash
curl -X POST https://api-retrieval.kai-studio.ai/retrieval/documents/list \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"instance_id": "ki_abc123", "offset": 0, "limit": 50}'
```

{% endtab %}
{% endtabs %}

## retrieval\_documents\_get\_document

Returns the metadata, summary (`resume`) and source URL of a specific document found via a semantic search or via `retrieval_documents_list`. It does **not** return the document's text: use `retrieval_documents_get_chunks` to read it. To get URLs for several documents cited by a search, prefer `retrieval_documents_list_by_ids` (one batch call).

### Input schema

| Field         | Type            | Required | Description               |
| ------------- | --------------- | -------- | ------------------------- |
| `instance_id` | string (`ki_*`) | yes      | K-AI instance identifier. |
| `document_id` | string (`kd_*`) | yes      | K-AI document identifier. |

### Output schema

| Field             | Type            | Description                                              |
| ----------------- | --------------- | -------------------------------------------------------- |
| `response.id`     | string (`kd_*`) | K-AI document identifier.                                |
| `response.name`   | string          | Document name.                                           |
| `response.url`    | string          | Clickable link to the document at its source.            |
| `response.resume` | string          | What the document is about.                              |
| `response.*`      | any             | Additional metadata depending on instance configuration. |

### Example

{% tabs %}
{% tab title="Python (MCP SDK)" %}

```python
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    url = "https://api-retrieval.kai-studio.ai/mcp"
    headers = {"Authorization": "Bearer YOUR_TOKEN"}
    async with streamablehttp_client(url, headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool(
                "retrieval_documents_get_document",
                {"instance_id": "ki_abc123", "document_id": "kd_def456"},
            )
            print(result.structuredContent)

asyncio.run(main())
```

{% endtab %}

{% tab title="TypeScript (MCP SDK)" %}

```ts
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://api-retrieval.kai-studio.ai/mcp"),
  { requestInit: { headers: { Authorization: "Bearer YOUR_TOKEN" } } }
);
const client = new Client({ name: "demo", version: "1.0.0" });
await client.connect(transport);
const result = await client.callTool({
  name: "retrieval_documents_get_document",
  arguments: { instance_id: "ki_abc123", document_id: "kd_def456" },
});
console.log(result.structuredContent);
```

{% endtab %}

{% tab title="Raw HTTP" %}

```bash
curl -X POST https://api-retrieval.kai-studio.ai/retrieval/documents/get-document \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"instance_id": "ki_abc123", "document_id": "kd_def456"}'
```

{% endtab %}
{% endtabs %}

## retrieval\_documents\_list\_by\_ids

Batch-fetches the metadata, summary and source URL of several documents in a single call — the recommended way to get links for the documents cited by a semantic search. Pass the `kd_*` identifiers from `retrieval_semantic_nodes_search` (`documents_contents[].document_id` or `semantic_nodes[].documents`).

### Input schema

| Field          | Type                                 | Required | Description                                                 |
| -------------- | ------------------------------------ | -------- | ----------------------------------------------------------- |
| `instance_id`  | string (`ki_*`)                      | yes      | K-AI instance identifier.                                   |
| `document_ids` | array of string (`kd_*`), minItems 1 | yes      | Document IDs to retrieve. Each must carry the `kd_` prefix. |

### Output schema

| Field               | Type            | Description                                   |
| ------------------- | --------------- | --------------------------------------------- |
| `response`          | array           | Document objects in unspecified order.        |
| `response[].id`     | string (`kd_*`) | K-AI document identifier.                     |
| `response[].name`   | string          | Document name.                                |
| `response[].url`    | string          | Clickable link to the document at its source. |
| `response[].resume` | string          | What the document is about.                   |
| `response[].*`      | any             | Additional metadata fields.                   |

### Example

{% tabs %}
{% tab title="Python (MCP SDK)" %}

```python
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    url = "https://api-retrieval.kai-studio.ai/mcp"
    headers = {"Authorization": "Bearer YOUR_TOKEN"}
    async with streamablehttp_client(url, headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool(
                "retrieval_documents_list_by_ids",
                {"instance_id": "ki_abc123",
                 "document_ids": ["kd_def456", "kd_ghi789"]},
            )
            print(result.structuredContent)

asyncio.run(main())
```

{% endtab %}

{% tab title="TypeScript (MCP SDK)" %}

```ts
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://api-retrieval.kai-studio.ai/mcp"),
  { requestInit: { headers: { Authorization: "Bearer YOUR_TOKEN" } } }
);
const client = new Client({ name: "demo", version: "1.0.0" });
await client.connect(transport);
const result = await client.callTool({
  name: "retrieval_documents_list_by_ids",
  arguments: {
    instance_id: "ki_abc123",
    document_ids: ["kd_def456", "kd_ghi789"],
  },
});
console.log(result.structuredContent);
```

{% endtab %}

{% tab title="Raw HTTP" %}

```bash
curl -X POST https://api-retrieval.kai-studio.ai/retrieval/documents/list-by-ids \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"instance_id": "ki_abc123", "document_ids": ["kd_def456", "kd_ghi789"]}'
```

{% endtab %}
{% endtabs %}

## retrieval\_semantic\_nodes\_search

Performs a semantic search inside a K-AI instance and returns the matched nodes from the Neural Semantic Graph along with the best-matching excerpts of the documents they originate from. An empty result means the instance has nothing on the subject: off-domain queries are answered empty on purpose. This operation does **not** call an LLM server-side: it returns raw semantic nodes and document content, letting the host LLM synthesise the final answer with full control over prompt and model.

### Input schema

| Field         | Type                 | Required | Description                                                                     |
| ------------- | -------------------- | -------- | ------------------------------------------------------------------------------- |
| `query`       | string (minLength 1) | yes      | Natural-language query.                                                         |
| `instance_id` | string (`ki_*`)      | yes      | K-AI instance identifier (from `retrieval_instances_list_available_instances`). |

### Output schema

| Field                                       | Type            | Description                                                                                                                                       |
| ------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `response.semantic_nodes`                   | array           | Relationship triples (`node_1`, `edge`, `node_2`), best first, each with its cited document ids (`kd_*`) and a `score` (similarity to the query). |
| `response.documents_contents`               | array           | One entry per retained document, best first.                                                                                                      |
| `response.documents_contents[].document_id` | string (`kd_*`) | K-AI document identifier.                                                                                                                         |
| `response.documents_contents[].name`        | string          | Document title.                                                                                                                                   |
| `response.documents_contents[].resume`      | string          | What the document is about.                                                                                                                       |
| `response.documents_contents[].score`       | number          | Relevance of the document to the query.                                                                                                           |
| `response.documents_contents[].content`     | array           | Excerpts in reading order, each `{chunk_id (kc_*), content}`. A short document comes back whole; a longer one returns its best-matching chunks.   |

### Example

{% tabs %}
{% tab title="Python (MCP SDK)" %}

```python
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    url = "https://api-retrieval.kai-studio.ai/mcp"
    headers = {"Authorization": "Bearer YOUR_TOKEN"}
    async with streamablehttp_client(url, headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool(
                "retrieval_semantic_nodes_search",
                {"instance_id": "ki_abc123",
                 "query": "refund policy for damaged goods"},
            )
            print(result.structuredContent)

asyncio.run(main())
```

{% endtab %}

{% tab title="TypeScript (MCP SDK)" %}

```ts
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://api-retrieval.kai-studio.ai/mcp"),
  { requestInit: { headers: { Authorization: "Bearer YOUR_TOKEN" } } }
);
const client = new Client({ name: "demo", version: "1.0.0" });
await client.connect(transport);
const result = await client.callTool({
  name: "retrieval_semantic_nodes_search",
  arguments: {
    instance_id: "ki_abc123",
    query: "refund policy for damaged goods",
  },
});
console.log(result.structuredContent);
```

{% endtab %}

{% tab title="Raw HTTP" %}

```bash
curl -X POST https://api-retrieval.kai-studio.ai/retrieval/semantic-nodes/search \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"instance_id": "ki_abc123", "query": "refund policy for damaged goods"}'
```

{% endtab %}
{% endtabs %}

## retrieval\_documents\_expand\_chunk

Returns the chunks immediately before and after an excerpt returned by `retrieval_semantic_nodes_search`, so the host LLM can read the passage around a hit. Use it when an excerpt is too short to answer confidently.

### Input schema

| Field         | Type            | Required       | Description                                                                          |
| ------------- | --------------- | -------------- | ------------------------------------------------------------------------------------ |
| `instance_id` | string (`ki_*`) | yes            | K-AI instance identifier.                                                            |
| `chunk_id`    | string (`kc_*`) | yes            | Chunk identifier, from `documents_contents[].content[].chunk_id` of a search result. |
| `window`      | integer (0–10)  | no (default 2) | How many chunks to include before **and** after the requested one.                   |

### Output schema

| Field                  | Type            | Description                     |
| ---------------------- | --------------- | ------------------------------- |
| `response`             | array           | Chunks in reading order.        |
| `response[].chunk_id`  | string (`kc_*`) | Chunk identifier.               |
| `response[].content`   | string          | Chunk text.                     |
| `response[].is_anchor` | boolean         | `true` for the requested chunk. |

Returns `503` (with `Retry-After`) when the knowledge base could not be read: retry, never read it as an empty passage.

### Example

{% tabs %}
{% tab title="Python (MCP SDK)" %}

```python
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    url = "https://api-retrieval.kai-studio.ai/mcp"
    headers = {"Authorization": "Bearer YOUR_TOKEN"}
    async with streamablehttp_client(url, headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool(
                "retrieval_documents_expand_chunk",
                {"instance_id": "ki_abc123",
                 "chunk_id": "kc_def456_12", "window": 2},
            )
            print(result.structuredContent)

asyncio.run(main())
```

{% endtab %}

{% tab title="TypeScript (MCP SDK)" %}

```ts
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://api-retrieval.kai-studio.ai/mcp"),
  { requestInit: { headers: { Authorization: "Bearer YOUR_TOKEN" } } }
);
const client = new Client({ name: "demo", version: "1.0.0" });
await client.connect(transport);
const result = await client.callTool({
  name: "retrieval_documents_expand_chunk",
  arguments: {
    instance_id: "ki_abc123",
    chunk_id: "kc_def456_12",
    window: 2,
  },
});
console.log(result.structuredContent);
```

{% endtab %}

{% tab title="Raw HTTP" %}

```bash
curl -X POST https://api-retrieval.kai-studio.ai/retrieval/documents/expand-chunk \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"instance_id": "ki_abc123", "chunk_id": "kc_def456_12", "window": 2}'
```

{% endtab %}
{% endtabs %}

## retrieval\_documents\_get\_chunks

Reads a whole document page by page, in reading order. Use it when a document must be read in full (for example a referenced specification), not to locate a passage: `retrieval_semantic_nodes_search` does that. Call it again with `offset = next_offset` while `has_more` is `true`.

### Input schema

| Field         | Type               | Required        | Description                            |
| ------------- | ------------------ | --------------- | -------------------------------------- |
| `instance_id` | string (`ki_*`)    | yes             | K-AI instance identifier.              |
| `document_id` | string (`kd_*`)    | yes             | K-AI document identifier.              |
| `offset`      | integer (0–100000) | no (default 0)  | Position of the first chunk to return. |
| `limit`       | integer (1–50)     | no (default 20) | Number of chunks per page.             |

### Output schema

| Field                        | Type             | Description                                                                       |
| ---------------------------- | ---------------- | --------------------------------------------------------------------------------- |
| `response.chunks`            | array            | Chunks of the page, in reading order.                                             |
| `response.chunks[].chunk_id` | string (`kc_*`)  | Chunk identifier.                                                                 |
| `response.chunks[].position` | integer          | Position of the chunk in the document.                                            |
| `response.chunks[].content`  | string           | Chunk text.                                                                       |
| `response.next_offset`       | integer          | Offset of the next page.                                                          |
| `response.has_more`          | boolean          | `true` while the document has more chunks.                                        |
| `response.missing_positions` | array of integer | Positions of this page the index does not hold: the text may be incomplete there. |

Returns `404` when the document does not exist, and `503` (with `Retry-After`) when the knowledge base could not be read: retry, never read it as the end of the document.

### Example

{% tabs %}
{% tab title="Python (MCP SDK)" %}

```python
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    url = "https://api-retrieval.kai-studio.ai/mcp"
    headers = {"Authorization": "Bearer YOUR_TOKEN"}
    async with streamablehttp_client(url, headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool(
                "retrieval_documents_get_chunks",
                {"instance_id": "ki_abc123",
                 "document_id": "kd_def456", "offset": 0, "limit": 20},
            )
            print(result.structuredContent)

asyncio.run(main())
```

{% endtab %}

{% tab title="TypeScript (MCP SDK)" %}

```ts
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://api-retrieval.kai-studio.ai/mcp"),
  { requestInit: { headers: { Authorization: "Bearer YOUR_TOKEN" } } }
);
const client = new Client({ name: "demo", version: "1.0.0" });
await client.connect(transport);
const result = await client.callTool({
  name: "retrieval_documents_get_chunks",
  arguments: {
    instance_id: "ki_abc123",
    document_id: "kd_def456",
    offset: 0,
    limit: 20,
  },
});
console.log(result.structuredContent);
```

{% endtab %}

{% tab title="Raw HTTP" %}

```bash
curl -X POST https://api-retrieval.kai-studio.ai/retrieval/documents/chunks \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"instance_id": "ki_abc123", "document_id": "kd_def456", "offset": 0, "limit": 20}'
```

{% endtab %}
{% endtabs %}