Skip to main content

Model Context Protocol

Sophic exposes your team's knowledge base to AI agents over the Model Context Protocol. Any MCP-compatible client — Claude Code, Claude Desktop, Cursor, Codex, Antigravity, ChatGPT connectors, or a custom agent — can search and read Sophic documents without custom integration code.

To connect a specific tool with copy-paste config, see Connect your AI tools.

Hosted vs. local​

There are two transports. They share the same three read tools with identical names and schemas; the local server adds two more.

HostedLocal
TransportStreamable HTTP at https://app.sophic.so/api/mcpstdio (@sophic/mcp-server via npx)
InstallNothing — point the client at the URLnpx -y @sophic/mcp-server@latest
AuthWorkspace API key (Authorization: Bearer)SOPHIC_API_KEY env var
PlanPaid plan (free workspaces get 402)Free
Toolssearch_knowledge_base, get_document, list_documentsthe three read tools + grep_knowledge_base + capture
Writes (capture)Not availableAvailable (needs a PAT + SOPHIC_WORKSPACE)

Use hosted for the simplest setup and remote clients; use local when you want grep/capture, you're on the free plan, or your client only speaks stdio.

  Hosted:  client ──HTTP──▶ https://app.sophic.so/api/mcp ──▶ knowledge base
  Local:   client ──stdio─▶ @sophic/mcp-server ──HTTP──▶ /api/v1/* + /api/ingest/cli

The local server's default API base URL is https://app.sophic.so.

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 (local transport)​

Most clients launch the server on demand with npx — no install needed:

npx -y @sophic/mcp-server@latest

You can also install it globally to get the sophic-mcp binary:

npm install -g @sophic/mcp-server

Environment variables​

The local 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.sophic.soSophic 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​

For per-tool, copy-paste config (Claude Code, Cursor, Codex, Antigravity, and more), see Connect your AI tools.

The general shape of a local (stdio) entry is:

{
  "mcpServers": {
    "sophic": {
      "command": "npx",
      "args": ["-y", "@sophic/mcp-server@latest"],
      "env": {
        "SOPHIC_API_KEY": "your-pat-or-api-key",
        "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.

Running manually​

SOPHIC_API_KEY=your-api-key npx -y @sophic/mcp-server@latest

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

Available tools​

The local server exposes five tools; the hosted transport exposes the first three (read-only).

ToolDescriptionTransport
search_knowledge_baseSemantic (vector) search across all documents in the workspaceHosted + local
get_documentFetch full details and content of a specific document by IDHosted + local
list_documentsList recent documents with paginationHosted + local
grep_knowledge_baseLiteral / regex line-level search — the ripgrep of the KBLocal only
captureSubmit a note to the capture buffer, attributed to the PAT ownerLocal only (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 the most relevant passages, with their document and heading context.

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​