v9 (current) v8
Edit Page

Sophia MCP Server

RESTHeart Cloud

Every Sophia instance exposes an MCP-compatible server, allowing any AI client to query its knowledge base directly — without going through the chat UI or the REST API.

What the MCP Server Exposes

Sophia organises its knowledge into Contexts. Each context defines an isolated knowledge domain with its own:

  • documents — files ingested into the knowledge base, tagged for access control

  • system prompt template — how the AI frames its answers

  • RAG options — how many documents to retrieve and inject into the prompt

  • MCP description — the text shown to AI clients when they list available tools

Each context is accessible at its own MCP endpoint: <base-url>/mcp/<context-id>/. When an AI client connects to that endpoint, it can use the Sophia tools to search and retrieve content scoped to that context only. A client connected to the restheart context cannot read documents that belong to the cloud context, and vice versa.

Within a context, documents are further organised by tags. Pass the optional tags parameter to sophia_search to narrow retrieval to documents carrying specific tags. Use sophia_list_tags to discover which tags are available.

For more on contexts, see the Administrator Guide.

SoftInstigate Public MCP Servers

SoftInstigate runs two public Sophia instances as live examples — no account or token required:

Context Url Knowledge base

restheart

https://sophia-api.restheart.com/mcp/restheart/

RESTHeart documentation, plugin API, configuration guides

cloud

https://sophia-api.restheart.com/mcp/cloud/

RESTHeart Cloud managed service docs

These are fully functional Sophia deployments managed by SoftInstigate. You can use them directly in your AI client.

To connect immediately with Claude Desktop, open Settings → Connectors → Add custom connector and paste the URL.

For Claude Code, run:

claude mcp add --transport http sophia-restheart https://sophia-api.restheart.com/mcp/restheart
claude mcp add --transport http sophia-cloud https://sophia-api.restheart.com/mcp/cloud

For private contexts, add the API token via the --header flag:

claude mcp add --transport http sophia-restheart https://<your-sophia>/mcp/<context>/ \
  --header "Authorization: Bearer <your-token>"

Clients with Streamable HTTP transport

Add this to the MCP settings:

{
  "sophia": {
    "type": "http",
    "url": "https://<your-sophia>/mcp/<context>/"
  }
}

Clients with stdio transport

Some clients (VS Code, Zed) spawn MCP servers as local processes and communicate over stdio. Use mcp-remote as a bridge. It requires Node.js >= 18 and is downloaded automatically by npx on first run.

Example configuration snippet:

{
    "sophia": {
      "command": "npx",
      "args": ["mcp-remote", "https://<your-sophia>/mcp/<context>/"]
    }
}

Private contexts

Private contexts require authentication. Sophia supports two approaches.

Claude Desktop supports OAuth natively. Open Settings → Connectors → Add custom connector, paste the context URL, and set OAuth Client ID to claude_desktop in the advanced settings. Sophia login page will open in the browser to complete the flow.

Via API token

Issue a token from the admin panel (see API Token Management). Pass it as an Authorization: Bearer header or, for clients that do not support custom headers, as a ?token=<jwt> query parameter.

Example configuration snippet:

{
  "sophia": {
    "type": "http",
    "url": "https://<your-sophia>/mcp/<context>/",
    "headers": {
      "Authorization": "Bearer <your-token>"
    }
  }
}

For clients that support stdio only:

{
    "sophia": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<your-sophia>/mcp/<context>/",
        "--header", "Authorization: Bearer <your-token>" ]
    }
}

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.