MCP Tools Reference

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

---

search_knowledge_base

Semantic search across all documents in the workspace.

Parameters:

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

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

Returns: JSON array of matching documents with similarity scores.

Example:

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

---

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: Full document object 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: JSON array of document summaries (no full content), ordered by updated_at descending.

Example:

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

---

capture

Ingest a note into the knowledge base. Runs the same smart-ingestion pipeline as the web editor: markdown cleanup, semantic dedup against existing documents, topic extraction, and folder linking. The document's author 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 and will be normalized server-side.
title	string	No	Optional title. If omitted, the server derives one from the content.
metadata	object	No	Optional free-form metadata stored with the document.

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 replays within the idempotency window return the original outcome instead of double-inserting.

Returns: A text summary of the ingestion outcome. The server's action field maps to:

action	Meaning	Response text
inserted	New document created	Captured new document <id>. View: <SOPHIC_API_URL>/documents/<id>
updated	Existing document updated (new version snapshot)	Updated existing document <id>.
skipped	Server-side dedup matched an existing document	Skipped — duplicate of document <target_id>.
flagged	Low-confidence capture sent to "Under Review"	Flagged for review (reason: <reason>, confidence <n>). Open Sophic to approve.
duplicate	Idempotency replay — the original call already landed	Idempotent replay — previous capture landed as document <id>.

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
• 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 API key, 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.