MCP Server

The Surchin MCP server integrates directly with Claude Code, giving your AI agent access to the shared knowledge substrate via six tools.

Installation

npx @surchin/surchin init

This adds Surchin to your Claude Code MCP configuration and creates a config file at ~/.config/surchin/config.json.

Configuration

Configuration is loaded from the following sources, highest priority first:

Environment variables: SURCHIN_API_KEY, SURCHIN_API_URL, SURCHIN_REPO_ID
Config file: ~/.config/surchin/config.json
Defaults: API URL → http://localhost:3000, repo ID → auto-detected from git

// ~/.config/surchin/config.json
{
  "apiKey": "sk_your_key_here",
  "apiUrl": "https://surchin.vercel.app",
  "repoId": "owner/repo"
}

Repo ID Auto-Detection

When no explicit repo ID is configured, the MCP server detects it automatically using this priority:

SURCHIN_REPO_ID environment variable
git remote get-url origin → extracts owner/repo
git rev-parse --show-toplevel → uses directory name
Empty string fallback

Available Tools

Tool	Description
`query_insights`	Search the knowledge substrate and load user preferences in one call
`deposit_insight`	Deposit a knowledge artifact (solution, pattern, pitfall, etc.)
`rate_insight`	Rate an insight as helpful or unhelpful
`get_friction_report`	Get a report of recurring errors and module friction
`set_preference`	Save a user preference that persists across sessions

query_insights

Search the knowledge substrate for relevant solutions, patterns, and pitfalls. Also returns the user's saved preferences automatically, so there's no need for a separate preferences call.

Param	Type	Required	Description
`query`	string	Yes	Natural-language search query
`file_context`	string[]	No	File paths for locality-boosted results
`error_signature`	string	No	Error message text for signature matching
`tag_context`	string[]	No	Tags to filter results by
`symbol_context`	string[]	No	Symbol names for locality-boosted results
`repo_id`	string	No	Repository identifier

deposit_insight

Deposit a knowledge artifact. Supports two modes:

Single mode

Provide content + kind as required parameters, plus optional fields.

Param	Type	Required	Description
`content`	string	Yes	Full text of the knowledge
`kind`	string	Yes	SOLUTION, PATTERN, PITFALL, CONTEXT, WORKFLOW, DEPENDENCY
`summary`	string	No	One-line summary (auto-generated if omitted)
`file_patterns`	string[]	No	File path patterns to anchor to
`symbol_names`	string[]	No	Symbol names to anchor to
`tags`	string[]	No	Categorization tags
`error_signature`	string	No	Error message for fingerprinting
`repo_id`	string	No	Repository identifier

Batch mode

Provide a deposits array where each item has content + kind plus any optional fields.

rate_insight

Rate an insight as helpful or unhelpful. Supports two modes:

Single mode

Provide insight_id + signal_type

Batch mode

Provide insight_ids[] + signal_type

Available signal types:

Signal	Effect
`POSITIVE`	Increases strength (agent found it helpful)
`NEGATIVE`	Decreases strength (agent found it unhelpful)
`HUMAN_UPVOTE`	Significantly increases strength (human confirmed quality)
`HUMAN_DOWNVOTE`	Significantly decreases strength (human flagged as wrong)

get_friction_report

Get a report of recurring errors and module friction points.

Param	Type	Required	Description
`error_text`	string	Yes	Error text to analyze
`file_path`	string	No	Scope to specific file
`repo_id`	string	No	Repository identifier

set_preference

Save a persistent preference that carries across sessions. Agents should call this proactively when they detect a preference signal — explicit statements (“I prefer...”), corrections, tool choices, or communication style preferences.

Param	Type	Required	Description
`category`	string	Yes	One of `approach`, `communication`, `values`, `domain`, `general`
`key`	string	Yes	Preference name (e.g., `complexity_tolerance`, `verbosity`)
`value`	any	Yes	The preference value (string, boolean, object, etc.)
`scope`	string	No	`personal` (default) or `team`

Best Practices

Query before starting any task — query_insights returns both knowledge and user preferences in one call
Query again with specific context after diagnosis — this second query is the most important
Deposit after every non-trivial task — implementations, bug fixes, patterns, architectural decisions. When in doubt, deposit
Always include file_context for better locality matching
Use batch deposit/rate for multiple items at session end
Watch for preference signals during the session and call set_preference immediately when detected — then tell the user what you remembered
Users can review and delete preferences from their dashboard at Settings → Preferences