---
title: "MCP Tools"
description: "Model Context Protocol tool definitions for XI Lucent: ingest, query, manage documents, and retrieve signed sources via LLM agents."
published: 2026-05-14T12:11:14.765418+00:00
updated: 2026-05-14T12:11:14.765418+00:00
tags: ["api", "lucent", "mcp", "reference"]
url: https://xiobjects.com/docs/xio/lucent/api/mcp
source: XI Objects
---

<!-- xion:doctype xion+markdown -->
<!-- xion:metadata
{
  "version": "1.0",
  "content_type": "application/xion\u002Bmarkdown",
  "source_type": "xi-content/doc",
  "generator": "xio-content-publisher/1.0.0",
  "generated": "2026-05-14T12:10:18.1320717\u002B00:00",
  "encoding": "utf-8",
  "render_intent": "markdown",
  "title": "MCP Tools",
  "slug": "xio/lucent/api/mcp",
  "copyright": "\u00A9 2026 XI Objects Inc"
}
-->

# MCP Tools

`Xio.Lucent.Mcp` exposes Lucent's core operations as Model Context Protocol tools. This lets LLM agents ingest documents, run searches, and retrieve signed source bytes without any additional HTTP surface.

## Setup

Mount the MCP tools into any MCP server host:

```csharp
builder.Services.AddLucent();
builder.Services.AddLucentMcpService();

builder.Services
    .AddMcpServer()
    .WithLucentTools();
```

`Xio.Lucent.Mcp.Host` is a ready-to-run stdio MCP server if you want to run Lucent as a standalone MCP process.

---

## lucent_add_document

Ingests a document into a collection. Accepts content as a string, a file path, or base64-encoded bytes.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `collectionId` | string | Yes | Collection to ingest into |
| `content` | string | No | Text content to ingest |
| `filePath` | string | No | Path to a file on disk |
| `contentBase64` | string | No | Base64-encoded binary content |
| `fileName` | string | No | File name for content type detection and provenance |
| `documentId` | string | No | Explicit document ID |
| `contentTypeHint` | string | No | Overrides content type detection |
| `metadata` | object | No | Key-value pairs attached to every chunk |
| `isXionContent` | bool | No | Trigger XION verification before ingestion |

Exactly one of `content`, `filePath`, or `contentBase64` must be provided.

**Returns:** Document ID, chunk count, content type, model ID, and per-stage durations.

---

## lucent_query

Runs hybrid vector + BM25 search against a collection.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `collectionId` | string | Yes | Collection to search |
| `text` | string | Yes | Natural language query |
| `topK` | integer | No | Maximum results to return (default 10) |
| `scoreThreshold` | number | No | Minimum score cutoff (0–1) |
| `filter` | object | No | Metadata filter expression tree |

**Returns:** Ranked list of scored chunks, each with content, metadata (including page number, heading, section path), and score breakdown (fused score, vector score, text score, source).

---

## lucent_delete_document

Removes a document and all its chunks from a collection.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `collectionId` | string | Yes | Collection containing the document |
| `documentId` | string | Yes | Document to delete |

---

## lucent_list_documents

Lists all documents in a collection.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `collectionId` | string | Yes | Collection to inspect |

**Returns:** Array of document records with document ID, content type, chunk count, model ID, source info, and ingest timestamp.

---

## lucent_get_signed_source

Retrieves the preserved XION bytes for a document that was ingested as XION content. Returns the complete signed artifact including the original trust block, suitable for independent re-verification.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `collectionId` | string | Yes | Collection containing the document |
| `documentId` | string | Yes | Document to retrieve |

**Returns:** Base64-encoded XION bytes, or a not-found indicator for non-XION documents.

---

## lucent_provision

Downloads and verifies the ONNX embedding model and sqlite-vec native extension. Must be called at least once before the engine can embed anything. Idempotent after initial download.

**Parameters:** None.

---

## Usage from an LLM agent

An agent can ingest and query in a single conversation turn:

```
Tool: lucent_add_document
  collectionId: "project-specs"
  filePath: "/workspace/specs/api-v2.pdf"
  metadata: { "version": "v2", "status": "draft" }

→ { documentId: "sha256:abc…", chunkCount: 87, contentType: "application/pdf" }

Tool: lucent_query
  collectionId: "project-specs"
  text: "rate limiting requirements"
  topK: 5
  filter: { type: "Eq", key: "version", value: "v2" }

→ [
    { score: 0.84, chunk: { content: "The API enforces…", metadata: { pageNumber: 12 } } },
    …
  ]
```

The agent receives chunk content and provenance metadata (page numbers, headings, section paths) alongside scores, so it can cite sources precisely.
<!-- xion:trust
{
  "v": 1,
  "canon_v": 1,
  "ctx": "xiobjects.com/content",
  "hash_blake3_hex": "e7948ba82a88144b30e9c8d9bde0f396075b43e73532f9427f07724c594a2507",
  "hash_sha256_hex": null,
  "sig_alg": "ed25519",
  "sig_b64": "61rGlzFeVq6_qIjG3GqxnhRcb8pe38j2I3UINkE1TjcrXyPMSkUl4-JwcRqtlfWsLqsoks-lZI7N9iRtWXz0CA",
  "pubkey_b64": "h-awvV8Rn-juph_c2Y7UH5A6e7NaFia3zBiMrJUOMOo",
  "x509_chain_pem": [
    "-----BEGIN CERTIFICATE-----\r\nMIIB9DCCAaagAwIBAgIQBrrNsmRlBvKQdA4idEliJjAFBgMrZXAwLjEsMCoGA1UE\r\nAwwjWEkgT2JqZWN0cyBJbmMgQ29udHJvbCBJbnRlcm1lZGlhdGUwHhcNMjYwNTEz\r\nMjI0NjA1WhcNMjYwNjEyMjI0NjA1WjBLMR4wHAYDVQQDDBV4aW8tY29udGVudC1w\r\ndWJsaXNoZXIxFzAVBgNVBAoMDlhJIE9iamVjdHMgSW5jMRAwDgYDVQQLDAdDb250\r\nZW50MCowBQYDK2VwAyEAh\u002BawvV8Rn\u002Bjuph/c2Y7UH5A6e7NaFia3zBiMrJUOMOqj\r\ngbwwgbkwDAYDVR0TAQH/BAIwADAOBgNVHQ8BAf8EBAMCB4AwEwYDVR0lBAwwCgYI\r\nKwYBBQUHAyQwZQYDVR0jBF4wXIAUOym3mFmw/qs1fgKrujCkxhrTk7KhLqQsMCox\r\nKDAmBgNVBAMMH0luc3RpdHV0ZSBvZiBQcm92ZW5hbmNlIFJvb3QgQ0GCFFJgN/ix\r\nQn72H6h3T5lEr9f8lJQFMB0GA1UdDgQWBBS1LSJi5\u002BeqBq8h974Ht9HTgIcdgTAF\r\nBgMrZXADQQCKjXbPwnk/DZHmLQstUWRzU6GSf\u002BSHTXTTZCtRLbmJKxT17Qlbpexc\r\nsRgdSpxNWpJPe9Fr4vwhRkESMqMIpgQO\r\n-----END CERTIFICATE-----\r\n",
    "-----BEGIN CERTIFICATE-----\r\nMIIByDCCAXqgAwIBAgIUUmA3\u002BLFCfvYfqHdPmUSv1/yUlAUwBQYDK2VwMCoxKDAm\r\nBgNVBAMMH0luc3RpdHV0ZSBvZiBQcm92ZW5hbmNlIFJvb3QgQ0EwHhcNMjUxMTAy\r\nMDMxNzEyWhcNMzAxMTAxMDMxNzEyWjAuMSwwKgYDVQQDDCNYSSBPYmplY3RzIElu\r\nYyBDb250cm9sIEludGVybWVkaWF0ZTAqMAUGAytlcAMhAFSS/pggSRmTcAMko7uc\r\nATH8OHgxVymd5mBFlPXbJkgio4GtMIGqMBIGA1UdEwEB/wQIMAYBAf8CAQAwDgYD\r\nVR0PAQH/BAQDAgEGMB0GA1UdDgQWBBQ7KbeYWbD\u002BqzV\u002BAqu6MKTGGtOTsjBlBgNV\r\nHSMEXjBcgBQAZRTDswSVORu\u002BkUOKX6WvrOvmQKEupCwwKjEoMCYGA1UEAwwfSW5z\r\ndGl0dXRlIG9mIFByb3ZlbmFuY2UgUm9vdCBDQYIUJqoJlpiSFg\u002B7W5IJLMrLttgR\r\nQp4wBQYDK2VwA0EA5FOht7YOsVRPp/FOKMQ\u002B3Mo9JxrvGR3ylKWAWNm6OUV7N3DB\r\nI9cD62wU5I0d0EKDBy0CX9DnoqUyxv5yguraAA==\r\n-----END CERTIFICATE-----\r\n",
    "-----BEGIN CERTIFICATE-----\r\nMIIBaTCCARugAwIBAgIUJqoJlpiSFg\u002B7W5IJLMrLttgRQp4wBQYDK2VwMCoxKDAm\r\nBgNVBAMMH0luc3RpdHV0ZSBvZiBQcm92ZW5hbmNlIFJvb3QgQ0EwHhcNMjUxMTAy\r\nMDMwNTEyWhcNMzUxMDMxMDMwNTEyWjAqMSgwJgYDVQQDDB9JbnN0aXR1dGUgb2Yg\r\nUHJvdmVuYW5jZSBSb290IENBMCowBQYDK2VwAyEAEWNZl\u002Br3IC7\u002BgBh90Yo1kWk1\r\npZCVzVuFdFT7qBBU8W2jUzBRMB0GA1UdDgQWBBQAZRTDswSVORu\u002BkUOKX6WvrOvm\r\nQDAfBgNVHSMEGDAWgBQAZRTDswSVORu\u002BkUOKX6WvrOvmQDAPBgNVHRMBAf8EBTAD\r\nAQH/MAUGAytlcANBAO6QeydOFNrN75qNyftggYudsxMyl4w9qWkSdZ6hlhrRcbSr\r\niG9Si0kbrIJOwYB/LTBU0RM4Rl\u002Bo9PM3Qp0mPwo=\r\n-----END CERTIFICATE-----\r\n"
  ],
  "key_id": "SDyVO7FvlAM-6CvQ62VZYOBO7JADFqLquUunUABRgKg",
  "created_at": "2026-05-14T12:10:18Z"
}
-->