v9 (current) v8
Edit Page

Sophia MCP Server

RESTHeart Cloud

Model Context Protocol (MCP) Integration

Sophia exposes a Model Context Protocol (MCP) server, allowing any MCP-compatible AI client or agent to query the Sophia knowledge base directly — without building a custom integration.

This makes it easy to connect tools like Claude Desktop, Cursor, VS Code, and other AI assistants to your Sophia knowledge base.

What is MCP?

The Model Context Protocol is an open standard that allows AI clients (assistants, agents, IDEs) to connect to external knowledge sources and tools. By exposing an MCP server, Sophia becomes a native knowledge source for any MCP-compatible client.

MCP Endpoint

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

The endpoint supports both HTTP (SSE) and stdio via mcp-remote transports.

Configuration

Clients with HTTP/SSE support

Clients that natively support HTTP transport (e.g. Claude Desktop ≥ 0.10, some IDE extensions) can connect directly:

RESTHeart documentation (on-prem):

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

RESTHeart Cloud knowledge base:

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

Clients without HTTP support (via mcp-remote)

For clients that only support stdio (e.g. older Claude Desktop versions, many CLI tools), use the mcp-remote bridge. It requires Node.js installed.

RESTHeart documentation (on-prem):

{
  "sophia": {
    "command": "npx",
    "args": ["mcp-remote", "https://sophia-api.restheart.com/mcp"],
    "env": {}
  }
}

RESTHeart Cloud knowledge base:

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

Request Headers

Header Required Description

X-Sophia-Tags

No

Filter knowledge base by tag (e.g. cloud). If omitted, searches all documents.

X-Sophia-Prompt

No

Select a custom prompt template (e.g. cloud). If omitted, the default prompt is used.

Client-specific Setup Examples

Claude Desktop

Edit the Claude Desktop configuration file (claude_desktop_config.json):

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Add under the mcpServers key:

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

Restart Claude Desktop. Sophia will appear as a connected tool in the sidebar.

Cursor / VS Code

In Cursor or VS Code with MCP support, add to your workspace or global MCP settings:

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

Claude Code (CLI)

Add Sophia to your project’s .mcp.json or global MCP config:

{
  "sophia": {
    "command": "npx",
    "args": ["mcp-remote", "https://sophia-api.restheart.com/mcp"],
    "env": {}
  }
}

Available MCP Tools

Once connected, the AI client gains access to these Sophia tools:

Tool Description

sophia_search

Semantic search over the RESTHeart knowledge base. Returns relevant text segments.

sophia_render_prompt

Builds a fully interpolated prompt including RAG context, ready to be sent to any LLM.

sophia_api

Returns the complete Sophia REST API reference.

Notes

  • No authentication is required for public Sophia instances.

  • mcp-remote requires Node.js ≥ 18. Install it from nodejs.org.

  • The npx mcp-remote command will be downloaded automatically the first time it runs.