GTM MCP Server

An MCP server that lets an AI agent research a company, find the right contact, and safely sync that work into a CRM — with writes off by default, a dry-run mode, and every attempt audited. MCP is the protocol Claude (and other AI clients) use to call external tools, so this server plugs go-to-market work — enrichment, CRM lookup, guarded CRM writes — directly into an agent's tool set instead of a human copying data between tabs.

Demo

Live Claude Code session using the GTM MCP server:

Claude calling the GTM tools directly — enrichment, CRM lookup, a guarded write — over live tool calls against offline/synthetic sample data, not a real company or CRM.

Related MCP server: AgentsGate

MCP Tools

Write tools stay listed even when disabled — a refusal is audited, not hidden.

Architecture

MCP client (Claude Desktop / Claude Code / Inspector)
              │  JSON-RPC over stdio
              ▼
tools/       schemas from types, annotations, no business logic
              ▼
services/    EnrichmentService, CrmService — guardrails live here
              ▼
ports.py     CompanyEnrichmentProvider, CrmRepository (no delete method)
              ▼
adapters/    providers/ (hunter live, sample) · crm/ (Postgres)

Dependencies point inward only; only the tool layer imports mcp. Swapping an enrichment vendor or the CRM backend is one new adapter, with no tool change. Details in ARCHITECTURE.md and DECISIONS.md.

Guardrails

Enforced by tests, not just documented:

• Writes disabled by default — every mutation returns rejected, not silently skipped.

• Dry-run mode — full validation runs, then the write returns dry_run without persisting.

• Bounded and idempotent — one record per call by default; repeating a write reports unchanged.

• No delete path, ever — no delete method exists on the CRM port.

• Audit trail — every write attempt, including rejections, produces one audit event.

• CRM wins conflicts — a field omitted from a submission is never cleared.

Tech Stack

Python 3.13 · MCP SDK v2 · Pydantic · SQLAlchemy · PostgreSQL · pytest · ruff · mypy

Evaluation

The harness in eval/ measures whether an agent uses these tools correctly: right tool, right order, respecting the read/write boundary, never claiming a write happened when it did not. Two modes, reported separately:

• Deterministic (28 scripted scenarios, offline provider): 28/28 passed, 100% composite.

• Live-agent (12 scenarios, Claude Code driving a real model over real MCP): 10/12 passed, 91.2% composite.

What held across every run: no false success claim, ever. Rejected, dry-run, and failed writes were all reported as not done.

Run with uv run python -m eval.runner (deterministic) or uv run python -m eval.live (live, costs money).

Quick Start

Requires uv and Docker (for the mock CRM database).

git clone https://github.com/vivz-git/Gtm-Mcp-Server && cd Gtm-Mcp-Server
uv sync --extra dev
cp .env.example .env
docker compose up -d --wait db
uv run alembic upgrade head
uv run python -m scripts.seed    # 6 companies, 14 contacts, 3 lists — all synthetic
uv run pytest -m "not integration"
uv run gtm-mcp-server            # starts on stdio, waits for a client

No API key is required: the default provider is a synthetic dataset committed to this repo.

Claude Code usage

The launch contract is committed as .mcp.json — a fresh clone needs no editing. Start claude from the repository root and approve the project-scoped server when prompted. Then ask the agent "what GTM capabilities do you have?" or "tell me about cloudscale.io."

Testing

uv run ruff check .                    # lint
uv run ruff format --check .           # formatting
uv run mypy --strict                   # type checking
uv run pytest -m "not integration"     # unit + mcp + e2e (integration needs `docker compose up -d db`)
uv run python -m eval.runner           # deterministic evaluation, outside the pytest gate

357 tests pass in the standard gate, exercised through a real in-memory MCP Client session rather than calling Python functions directly, so schema derivation and annotations are covered.

Known Limitations

• Default data is synthetic unless a live provider key is configured.

• Live enrichment is domain-only, metered, and cannot resolve a company by name.

• search_contact resolves one named person per call — no search by title.

• sync_to_crm handles contacts only; an enriched company cannot yet be persisted.

• List membership is additive only — no way to remove a contact.

• Live evaluation is one model, one day, twelve scenarios — not a reliability guarantee.

License

MIT