MCP Server

Automatic Install

The fastest way to get started. Run this in your project root:

npx @surchin/surchin init

This authenticates via your browser, then auto-detects your installed editors and configures each one:

Options

Remote MCP with OAuth

For MCP clients that support HTTP transport and OAuth discovery, use the hosted stateless endpoint instead of a local stdio bridge:

npx @surchin/surchin init --remote

This writes only the MCP URL, typically https://getsurch.in/api/mcp. Access and refresh tokens are not stored in project files or in the Surchin CLI config; your MCP client follows Surchin's OAuth metadata and manages authentication like Linear or Supabase MCP integrations.

{
  "mcpServers": {
    "surchin": {
      "url": "https://getsurch.in/api/mcp"
    }
  }
}

https://getsurch.in/api/mcp?api_key=surchin_mcp_YOUR_KEY

Manual Install

For editors that init doesn't auto-detect, or when you prefer to configure things yourself. Every MCP client needs the same three values:

Some editors split this into separate “Command” and “Arguments” fields. If yours does, enter npx as the command and -y @surchin/surchin@latest as the arguments.

Per-Editor Instructions

The command is always the same — only where you enter it changes.

{
  "mcpServers": {
    "surchin": {
      "command": "npx",
      "args": ["-y", "@surchin/surchin@latest"]
    }
  }
}

[mcp_servers.surchin]
command = "npx"
args = ["-y", "@surchin/surchin@latest"]

{
  "mcpServers": {
    "surchin": {
      "command": "npx",
      "args": ["-y", "@surchin/surchin@latest"]
    }
  }
}

{
  "mcpServers": {
    "surchin": {
      "command": "npx",
      "args": ["-y", "@surchin/surchin@latest"]
    }
  }
}

{
  "cline.mcpServers": {
    "surchin": {
      "command": "npx",
      "args": ["-y", "@surchin/surchin@latest"]
    }
  }
}

{
  "mcpServers": {
    "surchin": {
      "command": "npx",
      "args": ["-y", "@surchin/surchin@latest"]
    }
  }
}

{
  "mcpServers": {
    "surchin": {
      "command": "npx",
      "args": ["-y", "@surchin/surchin@latest"]
    }
  }
}

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:

1. Environment variables: SURCHIN_ACCESS_TOKEN, SURCHIN_REFRESH_TOKEN, SURCHIN_TOKEN, SURCHIN_API_URL, SURCHIN_REPO_ID
2. Config file: ~/.config/surchin/config.json
3. 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",
  "accessToken": "<jwt_access_token>",
  "refreshToken": "<jwt_refresh_token>"
}

Repo ID Auto-Detection

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

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

Available Tools

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.

deposit_insight

Deposit a knowledge artifact. Supports two modes:

Single mode

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

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

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.