v9 (current) v8
Edit Page

Sophia MCP Server

RESTHeart Cloud

Sophia MCP Server

Connect any MCP-compatible AI client to your RESTHeart knowledge base in minutes.

Endpoint: https://sophia-api.restheart.com/mcp — no authentication required for public knowledge bases.

Selecting a Context

Sophia supports multiple Contexts, each representing a distinct knowledge base with its own prompt template, tag filters, and RAG options. Select the desired context via the X-Sophia-Context header.

Context Knowledge base

restheart

RESTHeart documentation, plugin API, configuration guides

cloud

RESTHeart Cloud managed service docs

brewmaster

This is a demo about a fictional product: the BrewMaster Pro 3000 coffee maker (requires authentication)

Filtering by Tag

Within a context, documents are organized by tags. The optional X-Sophia-Tags header narrows retrieval to documents that carry all of the specified tags (comma-separated). Use sophia_list_tags to discover which tags are available in your context.

Header value Effect

(omitted)

All documents in the context are searched

restheart

Only documents tagged restheart are searched

cloud

Only documents tagged cloud are searched

restheart,plugin

Only documents tagged with both restheart and plugin are searched

RESTHeart

{
  "mcpServers": {
    "sophia-restheart": {
      "command": "npx",
      "args": ["mcp-remote", "https://sophia-api.restheart.com/mcp", "--header", "X-Sophia-Context: restheart"]
    }
  }
}

The restheart context covers both RESTHeart and RESTHeart Cloud documentation. To restrict retrieval to RESTHeart-only documents, add the X-Sophia-Tags header (see [_filtering_by_tag]):

{
  "mcpServers": {
    "sophia-restheart": {
      "command": "npx",
      "args": ["mcp-remote", "https://sophia-api.restheart.com/mcp",
               "--header", "X-Sophia-Context: restheart",
               "--header", "X-Sophia-Tags: restheart"]
    }
  }
}

RESTHeart Cloud

{
  "mcpServers": {
    "sophia-cloud": {
      "command": "npx",
      "args": ["mcp-remote", "https://sophia-api.restheart.com/mcp", "--header", "X-Sophia-Context: cloud"]
    }
  }
}

The snippets above use mcp-remote, a small Node.js bridge that exposes the HTTP endpoint as a local stdio process — the format most clients expect. It requires Node.js ≥ 18 and is downloaded automatically by npx on first run.

Clients that natively support HTTP/SSE transport (Cursor, VS Code, newer Claude Desktop) can connect directly without mcp-remote, using a simpler type: sse config — see below.

Client-specific notes

Claude Desktop — add the snippet above under mcpServers in claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows), then restart.

Cursor / VS Code — support HTTP natively; use "type": "sse" with a "headers" map instead of command/args:

{
  "sophia-restheart": {
    "type": "sse",
    "url": "https://sophia-api.restheart.com/mcp",
    "headers": { "X-Sophia-Context": "restheart" }
  }
}

Claude Code — add to your project’s .mcp.json or global MCP config.

Available Tools

Tool Description

sophia_search

Semantic search over the knowledge base. Returns relevant text segments with Source: filename and Path: directory for context expansion.

sophia_get_file

Retrieves the full content of a document by filename (all chunks merged in order). Use after sophia_search to read beyond the matched chunk.

sophia_list_files

Lists all accessible documents with tags and chunk count. Accepts an optional path parameter to filter by directory.

sophia_list_tags

Lists the tags available in the knowledge base, filtered by the active context and credentials.

sophia_list_paths

Lists immediate subdirectories under a given path prefix, like ls. Without arguments, returns top-level directories.

sophia_render_prompt

Builds a fully interpolated system prompt with RAG context injected, ready to send to any LLM as a system + user message pair.

sophia_api

Returns the complete Sophia REST API reference. Requires authentication — reserved for service administrators.

To maximise the context available to an AI agent:

  1. sophia_search — find relevant chunks; note the Source: filename and Path: directory in each result.

  2. sophia_get_file — retrieve the full file from Source: (not just the matched chunk).

  3. sophia_list_files with path=<Path:> — discover all related files in the same directory.

  4. sophia_get_file — retrieve any relevant sibling files.

To explore the knowledge base structure before searching:

sophia_list_paths          → top-level directories
sophia_list_paths(path=X)  → subdirectories under X
sophia_list_files(path=X)  → files in directory X
sophia_list_tags           → available tags