HG GTM Tools MCP

Internal MCP server for HG Insights GTM teams (Sales, CS, Marketing, Product). Powers AI-assisted outreach drafting, account research, customer support lookups, and admin via Claude Desktop.

What's MCP? Model Context Protocol — the standard Claude Desktop uses to call backend tools. This repo implements an MCP server that exposes GTM-specific tools (Salesforce lookups, Pylon issue search, account research, etc.). When a CSM types in Claude Desktop, Claude calls the tools defined here.

Setup

Prereqs: Python 3.11+, uv (install), and the Railway CLI for pulling env values. Don't have Railway access yet? Ask in #gtm-automation.

First time using Railway CLI? Run railway login to auth via browser before the steps below.

uv sync                                                                        # install deps
railway link -p 283ad9d5-e8d7-48d9-b380-10f9e5fab860 -e production             # link to hg-gtm-tools / production
railway variable list --kv > .env                                              # pull env values into a local .env
uv run pytest                                                                  # confirm setup works (37 tests, ~2s, no network)
uv run python -m src                                                           # run the server on http://localhost:8000/mcp

uv run pytest works on a fresh clone before you've populated .env — tests stub Clerk + Supabase + upstream HTTP. Production env vars come into play only when actually running the server (python -m src).

Production: https://hg-gtm-tools-mcp.madkudu.ai/mcp. Manifest at /tools/manifest (no auth, lists every registered tool). Deploy with railway up from the project root — see DEPLOYMENT.md.

Smoke-test live after deploy: uv run pytest tests/live/ -v (opens browser for OAuth on first run). Excluded from default pytest run.

Docs

Start here (contributor path):

• Adding a tool — end-to-end walkthrough for new tools

• Testing — fixtures and patterns

• Tool naming conventions

• Contributing — short reference for the contributor flow

Reference:

• Architecture — auth flow, async hand-off, layer responsibilities

• Deployment — how railway up works, sync jobs

• Development — research pipeline + API gotchas

• Super-Ops role — generic SOQL access

• Architecture Diagram / MCP App Diagram (open in browser)

Tools

Outreach creation (ops): create_outreach_draft, update_outreach_draft, list_drafts

Outreach viewing (ops, csm, am, manager, marketing): my_drafts, get_draft_detail, approve_draft, skip_draft

Research (ops, csm, am, manager, marketing): start_research, get_research_result, show_account_brief, get_account_detail

Book of Accounts (ops, csm, am, manager, marketing): get_book_of_accounts, update_last_outbound, clear_last_outbound_override

HG Data Catalogs (ops, csm, am, manager, marketing): hg_lookup_industry_codes, hg_lookup_intent, hg_lookup_products

HG Spend Categories (ops, csm, am, manager, marketing): hg_get_spend_categories

TrustRadius incentive budget (ops, csm, am, manager, marketing): tr_get_incentive_budget

TrustRadius reviews & campaigns (ops, csm, am, manager): tr_search_vendors, tr_get_review_report, tr_get_campaign_report

Vitally Success Plans (ops, csm, am, manager, marketing): vitally_show_success_plans, vitally_create_success_plan, vitally_update_success_plan

Customer Projects (ops, csm, am, manager, marketing): list_customer_projects

Contact search (ops, csm, am, manager, marketing): search_crm_contacts (zip + radius proximity)

Contact lookup (ops, csm, am, manager): lookup_contact

Pylon (ops, csm, am, pm, manager, marketing): pylon_search_accounts, pylon_search_issues, pylon_get_issue

Jira (ops, csm, am, pm, manager, marketing): jira_search_tickets, jira_get_ticket

Weflow (ops, csm, am, pm, manager, marketing): weflow_search_recordings, weflow_get_transcript

Knowledge Base (ops, csm, am, pm, manager, marketing): kb_search, kb_read, kb_flag_gap

CSM Stats (ops, csm, am, manager): get_csm_book_stats

Lookup (ops, csm, am, manager, marketing): lookup_account

Google Slides (ops, csm, am, manager, pm, marketing): google_slides

Admin (ops): list_users, create_user, update_user, delete_user

Salesforce Contact mutations (ops, csm, am, manager, marketing): crm_update_contact, crm_create_contact. Data-quality edits with overwrite protection and full audit log.

Super-Ops Salesforce (super_ops): crm_soql_query, crm_describe_sobject, crm_soql_update. Generic SOQL read/write + schema describe for trusted operators. Every call audited. See docs/super-ops-role.md.

Project Structure

src/
├── server.py            # FastMCP server + Clerk OIDC auth
├── __main__.py          # Uvicorn entry point
├── auth.py              # Current user from JWT claims
├── roles.py             # Role-based tool filtering (VALID_ROLES)
├── usage.py             # @tracked audit-log decorator
├── manifest.py          # /tools.json manifest endpoint for the dashboard
├── db.py                # Supabase CRUD (sync + async variants)
├── storage.py           # Supabase-backed AsyncKeyValue for OAuth state
├── geo.py               # State/country normalization + zip radius
├── product_map.py       # ProductCode → category mapping
├── tools/               # MCP tool handlers (one file per source)
│   ├── _shared.py       # @tool decorator (the contributor entry point)
│   ├── _registry.py     # Auto-discovery: walks this dir at startup
│   └── *.py             # One file per source — see `ls src/tools/`
├── clients/             # Async upstream API clients (one per service)
├── apps/                # MCP app bundles (Vite + vite-plugin-singlefile)
├── research/            # Account research pipeline (orchestrator + agents)
├── kb/                  # Knowledge base sync + read endpoints
└── sync/                # Scheduled sync jobs

tests/
├── conftest.py          # mcp_client, fake_user, mock_audit_log, env stubs
├── fixtures/upstreams.py  # mock_jira, mock_pylon, mock_salesforce, etc.
└── test_*.py            # one file per tool module being tested

docs/
├── adding-a-tool.md     # end-to-end walkthrough for new contributors
├── testing.md           # fixture reference
└── *.md                 # design docs and references

The tools/ directory is intentionally flat: one file per upstream source, auto-discovered at startup. Adding a new tool means dropping a file here. See docs/adding-a-tool.md.