MCP Server

The Surchin MCP server integrates directly with Claude Code, giving your AI agent access to the shared knowledge substrate via ten 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

Run surchin init to authenticate via your browser. Session tokens are saved to ~/.config/surchin/config.json and refreshed automatically.

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

Environment variables: SURCHIN_API_URL, SURCHIN_REPO_ID
Config file: ~/.config/surchin/config.json
Defaults: API URL → https://getsurch.in, repo ID → auto-detected from git

// ~/.config/surchin/config.json
// Managed by `surchin init` — do not edit manually
{
  "apiUrl": "https://getsurch.in",
  "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
`set_preference`	Save a user preference that persists across sessions
`end_session`	End the current session with an optional summary and handoff note for the next agent
`get_session_history`	Get recent session history with summaries and handoff notes
`get_skill`	Retrieve a skill's full instructions by ID or name
`create_skill`	Create or update a skill with triggers (tags, files, errors)
`list_groups`	List all groups accessible to the current user
`reconnect`	Re-authenticate when credentials expire (reloads config or opens browser)

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
`kinds`	InsightKind[]	No	Filter results to specific insight kinds (SOLUTION, PATTERN, PITFALL, CONTEXT, WORKFLOW, DEPENDENCY)
`limit`	integer	No	Maximum number of results to return (1–10, default 5)
`depth`	number	No	Retrieval depth: 0 = topic summaries only, 1 = top insight per cluster, 2 = full results (default)
`cluster_id`	string	No	Filter results to a specific topic cluster (use with depth=2 to drill into a cluster)
`expand_context`	boolean	No	When true (default) and a local code index exists, automatically expands `file_context` using the import/call graph to surface insights from related code. Set to false for pure semantic search.
`groups`	string[]	No	Filter results to specific groups by ID. Omit to search all accessible groups.

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
`group_id`	string	No	Group ID (UUID) to scope the deposit to a specific group. Omit for org-wide deposit.

Batch mode

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

rate_insight

Rate one or more insights as helpful or unhelpful. Positive signals strengthen them; negative signals weaken them. Supports two modes:

Single mode

Provide insight_id + rating

Batch mode

Provide insight_ids[] + rating

Param	Type	Required	Description
`insight_id`	string	No	ID of a single insight to rate
`insight_ids`	string[]	No	IDs of multiple insights to rate. Provide this OR `insight_id`, not both.
`rating`	string	Yes	`"helpful"` or `"unhelpful"`
`skill_id`	string	No	ID of a skill to provide feedback on
`skill_feedback`	string	No	`"followed"` or `"dismissed"` — feedback on whether the skill's instructions were used

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