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

Within an agent, documents are further organised by tags. Pass the optional tags parameter to search to narrow retrieval to documents carrying specific tags. Use tags to discover which tags are available.

For more on agents, see the Administrator Guide.

SoftInstigate Public MCP Servers

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

Agent Url Knowledge base

restheart

https://api.bysophia.ai/mcp/restheart/

RESTHeart documentation, plugin API, configuration guides

cloud

https://api.bysophia.ai/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://api.bysophia.ai/mcp/restheart
claude mcp add --transport http sophia-cloud https://api.bysophia.ai/mcp/cloud

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

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

Clients with Streamable HTTP transport

Add this to the MCP settings:

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

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/<agent>/"]
    }
}

Private agents

Private agents require authentication. An agent is private when its private field is true in the admin panel; access requires a JWT containing the agent id in the agents claim. Sophia supports three authentication paths.

Claude Desktop supports OAuth natively and can re-authenticate transparently when its JWT expires.

  1. In Claude Desktop open Settings → Connectors → Add custom connector

  2. Paste the agent URL (e.g. https://your-sophia/mcp/support/)

  3. Set OAuth Client ID to a value provisioned by your administrator (e.g. claude_desktop)

  4. Sophia’s login page opens in the browser; complete the flow to authorise the connector

Sophia exposes the standard OAuth metadata endpoints under /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource. The grant used after the initial user authorisation is client_credentials, so subsequent re-authentications are silent.

Issue a long-lived API token from the admin panel — see API Token Management — and pass it as an Authorization: Bearer header. Tokens are revocable.

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

Via ?token= query parameter (clients without custom headers)

Some clients (notably Claude Mobile and certain web wrappers) cannot attach custom headers. Sophia accepts the JWT as a ?token=<jwt> query parameter that is internally promoted to Authorization: Bearer <jwt>:

https://your-sophia/mcp/{agent}/?token=<your-token>

This is the same JWT issued by the admin panel — there is no separate token type.

Example configuration snippet:

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

For clients that support stdio only:

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

Available Tools

Tool Description

search

Semantic search over the knowledge base. Returns relevant text segments with Source: filename and Path: directory for context expansion. Supports an optional compact flag for source-only previews (~10× cheaper).

get

Retrieves a paginated page of a document by filename. Use after search to read beyond the matched chunk; pass page to navigate.

ls

Lists the contents of a directory in the knowledge base, like the Unix ls command. Returns both immediate subdirectories and files at the given path; accepts an optional path argument (omit to list the root level).

tags

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

prompt

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

api

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

ask / show

Interactive artifacts (forms / visualisations) rendered in an iframe by the client. Exposed only when the agent has collaborative: true in its options.
Note
 The context_* tools (session memory used by the agentic loop’s context management) are not exposed via MCP. They are internal tools called by Sophia’s own loop when agenticContextManagement: true, where the conversation persists across turns. MCP sessions are typically short-lived per client run, so server-side per-session memory is not useful there — MCP clients manage their own conversation state.