Skip to main content
Expose Moss semantic search and index management as tools for any MCP-compatible client using @moss-tools/mcp-server. Your AI assistant can create indexes, add documents, and run sub-10ms semantic queries without leaving the conversation.

​
Why use Moss with MCP?

MCP (Model Context Protocol) lets AI clients call external tools in a standardized way. The Moss MCP server gives any compatible client direct access to your knowledge base — no custom code, no API wrappers, no context window stuffing.

​
Required tools

  • Moss account with project credentials
  • Node.js 18+
  • An MCP-compatible client (Claude Desktop, Cursor, VS Code, etc.)

​
Integration guide

1

Get your Moss credentials

Sign in to the Moss Portal and copy your Project ID and Project Key from the project settings page.
2

Configure your MCP client

Add the Moss MCP server to your client’s configuration. Below are examples for common clients.
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
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"
      }
    }
  }
}
3

Start using Moss from your AI client

Once configured, your AI client can use Moss tools directly. Try prompts like:
  • “Create a Moss index called ‘product-docs’ with these FAQs…”
  • “Search my ‘product-docs’ index for return policy information”
  • “List all my Moss indexes”
  • “Load the ‘product-docs’ index for faster queries”

​
Available tools

The MCP server exposes the following tools to your AI client:
ToolDescription
querySemantic search over an index. Returns matching documents ranked by similarity. If the index was loaded with load_index, queries run locally (~1-10ms). Otherwise falls back to cloud (~100-500ms).
load_indexDownload an index into memory for fast local querying. Call this before querying an index repeatedly.

​
Index management

ToolDescription
create_indexCreate a new index with documents. Supports moss-minilm and moss-mediumlm embedding models.
list_indexesList all indexes in the project.
get_indexGet metadata and status for a specific index.
delete_indexDelete an index and all its documents.

​
Document operations

ToolDescription
add_docsAdd documents to an existing index. Supports upsert to update existing documents by ID.
get_docsRetrieve documents from an index. Returns all documents if no IDs are specified.
delete_docsDelete documents from an index by their IDs.

​
Jobs

ToolDescription
get_job_statusCheck the status of an async job (e.g., index builds triggered by other SDKs).

​
Configuration

​
Environment variables

VariableRequiredDescription
MOSS_PROJECT_IDYesYour Moss project ID.
MOSS_PROJECT_KEYYesYour Moss project key.
You can optionally set MOSS_CLOUD_API_BASE_URL to override the API base URL. Defaults to https://service.usemoss.dev.