@moss-tools/mcp-server

MCP (Model Context Protocol) server that exposes MOSS semantic search and index management as tools for any MCP-compatible client.

Queries automatically load indexes into memory on first use, giving <10ms local latency instead of ~1s cloud round-trips.

Quick Start

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "moss": {
      "command": "npx",
      "args": ["-y", "@moss-tools/mcp-server"],
      "env": {
        "MOSS_PROJECT_ID": "your-project-id",
        "MOSS_PROJECT_KEY": "your-project-key"
      }
    }
  }
}

Direct Usage

MOSS_PROJECT_ID=your-id MOSS_PROJECT_KEY=your-key npx @moss-tools/mcp-server

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | MOSS_PROJECT_ID | Yes | Your MOSS project ID | | MOSS_PROJECT_KEY | Yes | Your MOSS project key | | MOSS_CLOUD_API_BASE_URL | No | Overrides the cloud API base URL. Defaults to the production endpoint. |

How Querying Works

The query tool automatically loads the index into memory on the first call for each index. This means:

1. First query -- downloads the index locally (~1-2s one-time cost), then runs the query locally
2. Subsequent queries -- run entirely in-memory at <10ms latency

The server tracks which indexes are loaded and skips the download on repeat queries. Use load_index to pre-load specific indexes ahead of time and avoid the first-query latency. Mutations (add_docs, delete_docs, delete_index) invalidate the local copy so the next query re-downloads fresh data.

Tools

| Tool | Description | |------|-------------| | create_index | Create a new index with documents | | add_docs | Add documents to an existing index | | delete_docs | Delete documents by ID | | load_index | Pre-load an index into memory for fast local queries | | query | Semantic search (auto-loads index locally, <10ms after first load) | | list_indexes | List all indexes in the project | | get_index | Get metadata for an index | | delete_index | Delete an index | | get_docs | Retrieve documents from an index | | get_job_status | Check status of an async job |

Websites

| Tool | Description | |------|-------------| | create_web_source | Crawl a website into an index, optionally on a schedule | | list_web_sources | List the websites being indexed for this project | | get_web_source | Crawl status, last run, page and document counts | | resync_web_source | Re-crawl now | | set_web_source_refresh | Change the refresh cadence, or set it to manual | | delete_web_source | Stop crawling a website |

A crawl returns a jobId; poll it with get_job_status. On a re-crawl, unchanged pages are skipped, changed pages are replaced, and pages removed from the site have their documents deleted.

Documents

| Tool | Description | |------|-------------| | create_index_from_files | Upload local PDF or DOCX files and build an index from them, with OCR control. Returns a jobId to poll with get_job_status |

Pass parseOptions: { ocrMode: "full_ocr" } for scanned documents that have no text layer. auto_ocr runs OCR only on pages that appear to need it.

Programmatic Usage

import { createMossMcpServer, MossClient } from "@moss-tools/mcp-server";
import { MossClient as MossSdkClient } from "@inferedge/moss";

const restClient = new MossClient({
  projectId: "your-id",
  projectKey: "your-key",
});
const sdkClient = new MossSdkClient("your-id", "your-key");

const server = createMossMcpServer(restClient, sdkClient);
// Connect to any MCP transport

License

MIT