MCP Tools Reference

Parameter schemas for each tool exposed by the Sophic MCP server.

---

search_knowledge_base

Semantic (vector) search across all documents in the workspace. Use it for concepts, questions, and fuzzy phrases. For exact identifiers — env-var names, function names, error strings — prefer grep_knowledge_base.

Parameters:

Name	Type	Required	Default	Description
query	string	Yes	—	The search query
limit	number	No	5	Maximum chunks to return

Calls: GET /api/v1/search?q=<query>&limit=<limit>

Returns: The server's pre-formatted text block — the matched passages with heading breadcrumbs, ready for the model to read. (No matches found. when there are no hits.)

Example:

{
  "tool": "search_knowledge_base",
  "arguments": {
    "query": "production deployment checklist",
    "limit": 5
  }
}

---

grep_knowledge_base

Literal (or regex) line-level search across every document in the workspace — the ripgrep of the Sophic KB. Use it when you have an exact string to find.

Parameters:

Name	Type	Required	Default	Description
query	string	Yes	—	The exact substring (case-insensitive), or a POSIX regex if regex is true
regex	boolean	No	false	Treat query as a POSIX regex
limit	number	No	50	Maximum matching lines (max 200)
max_per_doc	number	No	5	Cap on matching lines per document

Calls: GET /api/v1/grep?q=<query>&regex=<bool>&limit=<limit>&max_per_doc=<n>

Returns: Ripgrep-shaped lines — <title> (<id>):<line>: <text>. (No matches found. when there are no hits.)

Example:

{
  "tool": "grep_knowledge_base",
  "arguments": {
    "query": "SOPHIC_API_KEY"
  }
}

---

get_document

Fetch full details and content of a specific document by ID.

Parameters:

Name	Type	Required	Description
id	string	Yes	The document ID to fetch

Calls: GET /api/v1/documents/<id>

Returns: The full document object (pretty-printed JSON), including content.

Example:

{
  "tool": "get_document",
  "arguments": {
    "id": "abc123"
  }
}

---

list_documents

List recent documents in the knowledge base.

Parameters:

Name	Type	Required	Default	Description
limit	number	No	50	Maximum number of documents to list
offset	number	No	0	Pagination offset

Calls: GET /api/v1/documents?limit=<limit>&offset=<offset>

Returns: The { results: [...] } envelope (pretty-printed JSON) — document summaries (no full content), ordered by updated_at descending.

Example:

{
  "tool": "list_documents",
  "arguments": {
    "limit": 20,
    "offset": 0
  }
}

---

capture

Submit a note to the workspace's capture buffer. Captures are not turned into documents synchronously — they land in an immutable buffer, and a background librarian sweep later consolidates buffered captures into documents (deduping, tagging topics, and filing them into folders). The author of every capture is derived server-side from the PAT owner's profile — the MCP never sends an author field.

Auth: Personal Access Token with the capture scope. Workspace API keys are rejected with a 403 from /api/ingest/cli because capture requires user attribution. SOPHIC_WORKSPACE must be set in the MCP config.

Parameters:

Name	Type	Required	Description
content	string	Yes	The note body. Markdown is supported.
title	string	No	Optional title. If omitted, the server derives one from the content.
metadata	object	No	Optional free-form metadata stored with the capture.

Calls: POST /api/ingest/cli with headers:

Authorization: Bearer <SOPHIC_API_KEY>
x-sophic-workspace: <SOPHIC_WORKSPACE slug>
x-sophic-idempotency-key: <fresh UUID per call>
Content-Type: application/json

The idempotency key is generated via crypto.randomUUID() on every invocation, so a retry of a timed-out request replays the same key and short-circuits instead of double-inserting.

Returns: A summary of the outcome. The server's action field can be:

action	HTTP	Meaning	Surfaced as
inserted	201	The capture was promoted straight to a document	Captured new document <id>. View: <SOPHIC_API_URL>/documents/<id>
buffered	202	The capture was queued for the next librarian sweep	The raw acknowledgment JSON ({ "ok": true, "action": "buffered", "capture_id": "…" })
duplicate	200	Idempotent replay — the original call already landed	Idempotent replay — previous capture landed as document <id>.
in_flight	409	A concurrent first caller hasn't recorded a result yet — back off and retry	Error: Sophic API Error (409): Duplicate request in flight

Example:

{
  "tool": "capture",
  "arguments": {
    "content": "Decision: we're pinning Next.js to 15.1.x until the App Router streaming bug is fixed upstream.",
    "title": "Next.js version pin"
  }
}

Error cases:

• Missing or empty content → Error: content is required
• Capture too short (below the minimum word count) → server returns 400 (Capture too short)
• SOPHIC_WORKSPACE not configured → Error: SOPHIC_WORKSPACE is required for the capture tool. Set it in your MCP config to your workspace slug.
• PAT lacks capture scope → server returns 403, surfaced as Error: Sophic API Error (403): Missing required scope: capture
• Workspace API key used instead of PAT → server returns 403, surfaced as Error: Sophic API Error (403): This endpoint requires a user credential

---

Error handling

If a tool call fails (e.g., invalid credential, network error, document not found), the MCP server returns an error response:

{
  "content": [{ "type": "text", "text": "Error: Sophic API Error (401): Unauthorized" }],
  "isError": true
}

The agent receives the error message and can inform the user or retry.