Skip to main content

Model Context Protocol

Sophic provides an MCP server (@sophic/mcp-server) that exposes your team's knowledge base to AI agents. Any MCP-compatible client — Claude Code, Claude Desktop, Cursor, or a custom agent — can search, list, read, and capture Sophic documents without custom integration code.

Architecture​

┌─────────────────┐         stdio          ┌──────────────┐
│  AI Agent        │ ◀──────────────────── │  sophic-mcp    │
│  (Claude, etc.)  │                        │  server       │
└─────────────────┘                        └──────┬───────┘
                                                   │ HTTP
                                                   ▼
                                            ┌──────────────┐
                                            │  Sophic API    │
                                            │  /api/v1/*   │
                                            └──────────────┘

The MCP server runs locally and communicates with your agent over stdio. It authenticates with Sophic using either a workspace API key (read tools only) or a Personal Access Token (PAT, required for the capture write tool) and proxies tool calls to the /api/v1/* and /api/ingest/cli REST endpoints.

Setup​

Prerequisites​

  • For read tools: a Sophic workspace API key or a Personal Access Token (generate either at /settings/developer in the dashboard).
  • For the capture tool: a Personal Access Token with the capture scope. Workspace API keys are rejected server-side because capture requires user attribution. PATs are one-to-one with a user — the author of each captured document is derived from the PAT owner's profile, not sent by the MCP.

Installation​

npm install -g @sophic/mcp-server

This installs the sophic-mcp binary.

Environment variables​

The MCP server reads the following environment variables:

VariableRequiredDefaultDescription
SOPHIC_API_KEYYes—Workspace API key or Personal Access Token. PAT is required for the capture tool.
SOPHIC_API_URLNohttps://app.sophichq.coSophic API base URL
SOPHIC_WORKSPACENo (Yes for capture)—Workspace slug. Required when SOPHIC_API_KEY is a PAT — identifies which workspace to scope requests to (PATs can belong to users with multiple workspace memberships). Also required when invoking capture.

Connecting to an agent​

Claude Code​

Add to your MCP config (~/.claude/mcp.json):

{
  "mcpServers": {
    "sophic": {
      "command": "sophic-mcp",
      "env": {
        "SOPHIC_API_KEY": "your-pat-or-api-key",
        "SOPHIC_API_URL": "https://app.sophichq.co",
        "SOPHIC_WORKSPACE": "your-workspace-slug"
      }
    }
  }
}

SOPHIC_WORKSPACE is optional when SOPHIC_API_KEY is a workspace API key but required when it is a PAT or when the agent invokes the capture tool.

Claude Desktop​

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "sophic": {
      "command": "sophic-mcp",
      "env": {
        "SOPHIC_API_KEY": "your-pat-or-api-key",
        "SOPHIC_API_URL": "https://app.sophichq.co",
        "SOPHIC_WORKSPACE": "your-workspace-slug"
      }
    }
  }
}

Running manually​

SOPHIC_API_KEY=your-api-key sophic-mcp

The server starts on stdio and logs Sophic MCP Server started to stderr.

Available tools​

The MCP server exposes four tools:

ToolDescriptionAuth
search_knowledge_baseSemantic search across all documents in the workspaceAPI key or PAT
get_documentFetch full details and content of a specific document by IDAPI key or PAT
list_documentsList recent documents with paginationAPI key or PAT
captureIngest a note into the knowledge base. Dedups, auto-formats, topic-tags, and attributes the document to the PAT owner.PAT with capture scope + SOPHIC_WORKSPACE

For parameter schemas and examples, see MCP Tools.

Example interaction​

Once connected, your agent can invoke Sophic tools naturally:

Agent: I'll check Sophic for deployment procedures.
       [calls search_knowledge_base with query "production deployment steps"]

Sophic returns 3 matching documents with similarity scores.

Agent: Based on the team's documentation, here are the deployment steps...

The agent gets real, up-to-date context from your team's knowledge base.

Security​

  • The MCP server authenticates using either a workspace API key (read tools only) or a Personal Access Token (required for capture) — both are scoped to a single workspace and can be revoked from /settings/developer.
  • For capture, the author of every ingested document is derived server-side from the PAT owner's profile (profiles.display_name / email). The MCP never sends an author field — the agent cannot spoof attribution.
  • The credential is passed via environment variable and never transmitted to the agent or included in tool responses.
  • All requests to Sophic use HTTPS with the Authorization: Bearer header; the capture tool additionally sends x-sophic-workspace (workspace slug) and a fresh x-sophic-idempotency-key UUID per call so retries are safe.

Next steps​