gopher-mcp

Gopher MCP

Drive the Gopher lead pipeline from natural language via the Model Context Protocol.

Demo

• Loom walkthrough (60s):
• Install matrix (Claude Desktop / Claude Code / ChatGPT Custom Actions / Cursor IDE):

Gopher MCP exposes the full Gopher lead-intelligence pipeline as 18 MCP tools. Any AI assistant that speaks MCP (Claude Desktop, Claude Code, Cursor, Windsurf) can configure segments, queue prospect discovery, and pull enriched leads — all from a single natural-language utterance.

Requirements

• Bun v1.0 or later
• A Gopher API key (gph_...) — create one in the Gopher dashboard under Settings → API Keys
• The Gopher API server (self-hosted dev or production at https://gopher.it.com)

Installation

For Claude Code / Cursor / Windsurf (via .mcp.json)

Add the following to your project's .mcp.json file (or create one at the repo root):

// .mcp.json — picked up automatically by Claude Code, Cursor, and other MCP-aware editors
{
  "mcpServers": {
    "gopher-mcp": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/mcp-product/src/index.ts"],
      "env": {
        "GOPHER_API_KEY": "gph_replace_me",
        "GOPHER_API_BASE_URL": "https://gopher.it.com"
      }
    }
  }
}

Replace /absolute/path/to/mcp-product/src/index.ts with the real path on your machine — e.g. /home/alice/projects/gopher/mcp-product/src/index.ts.

For local development against a running Next.js dev server (bun run dev), set:

{
  "mcpServers": {
    "gopher-mcp": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/mcp-product/src/index.ts"],
      "env": {
        "GOPHER_API_KEY": "gph_replace_me",
        "GOPHER_API_BASE_URL": "http://localhost:3000"
      }
    }
  }
}

For Claude Desktop

Paste the same JSON block into your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Example (add the mcpServers key if it doesn't exist yet):

{
  "mcpServers": {
    "gopher-mcp": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/mcp-product/src/index.ts"],
      "env": {
        "GOPHER_API_KEY": "gph_your_real_key_here",
        "GOPHER_API_BASE_URL": "https://gopher.it.com"
      }
    }
  }
}

Restart Claude Desktop after saving. The gopher-mcp server should appear in Developer → MCP Servers as "connected".

Note: npx gopher-mcp (global install via npm) is deferred to Phase 02.5. Use the bun run /path/to/src/index.ts form for now.

Environment Variables

Variable	Required	Default	Description
GOPHER_API_KEY	Yes	—	Bearer API key (gph_...). Generate at Gopher dashboard → Settings → API Keys. The server exits immediately if this variable is missing.
GOPHER_API_BASE_URL	No	https://gopher.it.com	Base URL of the Gopher REST API. Set to http://localhost:3000 for local dev.

Copy mcp-product/.env.example to mcp-product/.env and fill in GOPHER_API_KEY to run the server directly (bun run src/index.ts). The .mcp.json env block takes precedence over any .env file when the server is launched by your AI client.

Tool Catalog

All 18 tools are grouped by functional family below. Each tool returns a JSON response or an isError: true MCP error with a human-readable message on failure.

ICP — Segments and Personas

Tool	Description	Key Inputs
list_segments	List ICP segments for the authenticated org. Supports pagination.	limit, offset
list_personas	List personas for the authenticated org, optionally filtered by segment.	limit, offset, segment_id
create_persona	Create a persona attached to a segment.	name (required), segmentId (required), jobTitles, pains, desiredOutcomes, seniority, decisionInfluence

Discovery — Leads and Companies

Tool	Description	Key Inputs
get_leads	List enriched leads for the authenticated org, optionally filtered by segment or persona.	limit, offset, segment_id, persona_id
get_companies	List enriched companies for the authenticated org, optionally filtered by status or name.	limit, offset, status, name
upload_companies	Upload an array of companies for qualification via the Weasel pipeline. Returns queued count and job IDs.	companies (required, max 100)

Account — Org and Quotas

Tool	Description	Key Inputs
get_pipeline_progress	Get pipeline progress counts (prospects uploaded/enriched, leads discovered/enriched) bucketed by today, week, month, and all-time.	—
get_daily_limits	Get the authenticated org's daily quota for discovery and enrichment.	—
get_org	Get the authenticated org's profile (id, name, plan tier).	—
get_targets	Get per-segment allocation shares for the authenticated org. Shares always sum to 1.0.	—
set_targets	Set per-segment allocation shares. Provide [{ segmentId, share }] objects whose share values sum to 1.0.	targets (required)

Taxonomy — Industry Classification

Tool	Description	Key Inputs
classify_company	Classify a single company into the canonical industry taxonomy. Returns industryId, confidence, and lookup method.	name (required), website, country, naics, sic
get_industry_node	Get a taxonomy node's full ancestor chain and cross-references to NAICS, ISIC, GICS, SIC, etc. by industry id.	id (required)
resolve_taxonomy_code	Resolve an external taxonomy code (e.g. NAICS_2022 522110) to its canonical industry node.	taxonomy (required), code (required), all_parents

System

Tool	Description	Key Inputs
health_check	Probe the Gopher API health endpoint. Returns { status: "ok" } on success. Useful for verifying the API key and base URL are configured correctly.	—

Engine — AI-Native Pipeline (Wave C)

Tool	Description	Key Inputs
create_segment_from_description	Generate a structured ICP segment from a free-form natural-language description. Returns a CreateSegmentRequest object — does NOT persist. Pass the result to POST /api/segment (or review with the user) before running discovery.	description (required, 10–4000 chars)
run_discovery	Queue an autonomous Weasel discovery run for an existing segment. Returns a jobId — poll it with get_job_status. The caller's org must own the segment; otherwise the call returns 404.	segmentId (required), limit
get_job_status	Poll the status of a discovery job. Returns state (created → active → completed), output, and an archivedNote explaining the 1-hour retention window. Completed jobs older than 1 hour return 404 — interpret as success-but-archived.	jobId (required, UUID)

Example Prompts

These prompts work end-to-end from a single utterance — the AI assistant chains the relevant tools automatically.

Find leads in a new vertical:

"Use Gopher to find 10 CFOs at mid-market logistics companies in the GCC."

Expected tool chain: create_segment_from_description → (user persists segment) → run_discovery → get_job_status (until completed) → get_leads

Create a full segment + discovery run:

"Create a Gopher segment for fintech CTOs at companies in series-B funding stage in the US, then start discovery for up to 20 prospects."

Expected tool chain: create_segment_from_description → (persist via POST /api/segment) → create_persona → run_discovery → get_job_status

Check job progress:

"What's the status of Gopher discover job abc-123? If completed, list the discovered leads."

Expected tool chain: get_job_status → (if completed) get_leads

Inspect taxonomy for a company:

"Classify Maersk into Gopher's industry taxonomy and show me the full ancestor chain."

Expected tool chain: classify_company → get_industry_node

Check org quota before running discovery:

"Show me the Gopher org profile and remaining daily limits before I queue any discovery jobs."

Expected tool chain: get_org → get_daily_limits

Architecture

The Gopher MCP server is a lightweight stdio process built on @modelcontextprotocol/sdk. It communicates with AI clients over stdin/stdout using the Model Context Protocol JSON-RPC framing — no HTTP server is involved on the MCP layer itself.

All tool calls are forwarded to the Gopher REST API at GOPHER_API_BASE_URL using a Bearer Authorization header constructed from GOPHER_API_KEY. The server holds no state and does not access the database directly — it is a thin authenticated proxy over the public Gopher API.

The full pipeline (create_segment_from_description → persist → run_discovery → get_job_status → get_leads) can be driven end-to-end from a single natural-language utterance, with the AI assistant orchestrating the tool calls and surfacing results. The Wave C engine tools (create_segment_from_description, run_discovery, get_job_status) wrap the three Wave B REST routes (POST /api/segment/extract, POST /api/engine/discover, GET /api/engine/jobs/{jobId}) introduced in Phase 02.4.

All 18 tools are registered at startup. The discovery tag is icp for segmentation tools, discovery for company/lead tools, account for org/quota tools, classification for taxonomy tools, and system for health.

Troubleshooting

Error: GOPHER_API_KEY environment variable is required

The server exits immediately if GOPHER_API_KEY is not set. Make sure the env block in your .mcp.json or claude_desktop_config.json includes GOPHER_API_KEY with a real gph_... value.

401 on tool calls

The API key is invalid, expired, or revoked. Regenerate it at Gopher dashboard → Settings → API Keys → Create and update your .mcp.json.

429 on tool calls

The org has hit its rate limit (60 GET requests/min, 20 write requests/min) or its daily discovery cap. Back off and retry, or check get_daily_limits to see remaining quota.

get_job_status returns 404 with archivedNote

The discovery job completed more than 1 hour ago. pg-boss archives completed jobs after archiveCompletedAfterSeconds = 3600. A 404 from this endpoint on a job you previously saw as completed is expected — treat it as success-but-archived and proceed to get_leads.

get_job_status returns 400 Invalid jobId

The jobId argument is not a valid UUID. Ensure you pass the exact UUID string returned by run_discovery, not a placeholder or truncated value.

list_personas returns 404

This would indicate a URL routing bug. The server uses /api/persona (singular), which is the correct route. If you see 404 here, check that your GOPHER_API_BASE_URL points to a running Gopher instance.

MCP server not listed in AI client

Restart the AI client after editing .mcp.json or claude_desktop_config.json. Claude Desktop loads MCP config only at startup; Claude Code re-reads .mcp.json on restart or project open.

License

Proprietary — version 0.1.0. See https://gopher.it.com/terms.