getsonar-mcp 0.1.8

MCP server for SONAR — KYB due diligence, competitive intelligence, and strategic accounts research for AI agents.

getsonar-mcp

MCP server for SONAR — KYB due diligence, competitive intelligence, and strategic accounts research for AI agents.

Works with Claude Desktop, Claude Code, Cursor, Windsurf, Continue.dev, and any other Model Context Protocol client.

What it does

Tools for:

• KYB compliance — corporate registries, sanctions screening (OFAC/UN/EU/UK), FCA Register lookup, directors, UBOs, adverse media
• Competitive intelligence — pricing changes, hiring signals, product updates, customer sentiment, corporate events
• Strategic accounts research — buying signals, trigger events
• Async narrated reports — /run calls return AI-narrated reports written by Claude (compliance-officer-ready)

Two call shapes per agent:

• /findings — fast structured signals (~30-90s sync). Use when your agent will do its own analysis.
• /run — full report with Claude analysis (~3 min async, returns a run_id you poll).

Pricing: new accounts get 3 free trial calls (any endpoint, lifetime — not monthly). After that:

Endpoint	Price
/findings (any agent)	€0.40
/run (any agent)	€2.00

Top up your account from €5 at getsonar.report/developer/keys, or pick a monthly plan at getsonar.report/settings.

Get an API key

1. Sign up at getsonar.report
2. Go to API Keys in the sidebar
3. Click Create API Key, copy the sk-sonar-... key
4. (Optional) Top up your account balance from €5 once you've used your three free trial calls

Use without an MCP client (plain HTTP)

Don't need an MCP integration? Hit the SONAR API directly with curl, Python, JavaScript, or any HTTP client. The MCP server is just a thin wrapper over these endpoints.

Quickstart with curl

# 1. Set your key
export SONAR_API_KEY=sk-sonar-...

# 2. Fast structured findings — sync, ~30-90s, €0.40 per call
curl -X POST 'https://api.getsonar.report/v1/agents/company-intelligence/findings' \
  -H "X-API-Key: $SONAR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"company_name":"Stripe","website":"https://stripe.com"}'

# 3. Full AI-narrated report — async, ~3 min, €2.00 per call
curl -X POST 'https://api.getsonar.report/v1/agents/company-intelligence/run' \
  -H "X-API-Key: $SONAR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"company_name":"Stripe","website":"https://stripe.com"}'
# → returns {"run_id": "...", "status": "queued"}

# 4. Poll the status until status="completed"
curl 'https://api.getsonar.report/v1/agents/company-intelligence/runs/RUN_ID' \
  -H "X-API-Key: $SONAR_API_KEY"

Available agents

Replace company-intelligence in the URL with any of these:

Agent	Use case
company-intelligence	Competitive intelligence — pricing, hiring, product, news
kyb-diligence	KYB / AML compliance — registries, sanctions, UBOs, adverse media
strategic-accounts	B2B sales research — buying signals, trigger events
adverse-media	Targeted negative-news screening across 8 languages

Account & balance

# Check balance + remaining free trial calls
curl 'https://api.getsonar.report/v1/account' -H "X-API-Key: $SONAR_API_KEY"

Tips

• Always include website — the URL disambiguates generic-noun company names ("Stripe", "Apple", "Square") from unrelated entities sharing the brand word. Without a website, results may include irrelevant news collisions.
• /findings is cheap and synchronous. Use it when your downstream agent will do its own reasoning.
• /run is the full report. Async-only — submit, poll the run-id endpoint, expect ~3 min.
• Free trial: 3 calls of any kind, lifetime. After that the per-call price kicks in from your prepaid balance (top-up flow at /developer/keys) or your monthly subscription quota.
• SSRF guard: the website field must be http:// or https:// — unscoped strings, file://, and private IPs are rejected with HTTP 400.
• Pretty output: append ?pretty=1 to any endpoint URL for indented JSON during terminal exploration (e.g. /v1/usage?pretty=1). Default is compact for bandwidth.

Full OpenAPI spec at api.getsonar.report/docs.

---

Install (MCP server)

Recommended: uvx (no install needed)

If you have uv installed (most modern Python setups), nothing to install — uvx getsonar-mcp runs the latest version on demand.

Alternative: pipx

pipx install getsonar-mcp

Configure your MCP client

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "sonar": {
      "command": "uvx",
      "args": ["getsonar-mcp"],
      "env": {
        "SONAR_API_KEY": "sk-sonar-YOUR_KEY_HERE"
      }
    }
  }
}

Restart Claude Desktop. The 7 tools should appear in the 🔌 menu.

Claude Code

Add to your project's .mcp.json or run:

claude mcp add sonar -- uvx getsonar-mcp
# Then in your shell: export SONAR_API_KEY=sk-sonar-...

Or with the env var inline:

claude mcp add sonar --env SONAR_API_KEY=sk-sonar-... -- uvx getsonar-mcp

Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "sonar": {
      "command": "uvx",
      "args": ["getsonar-mcp"],
      "env": {
        "SONAR_API_KEY": "sk-sonar-YOUR_KEY_HERE"
      }
    }
  }
}

Windsurf / Continue.dev

Same config shape as Claude Desktop. See your client's MCP docs for the config file path.

Configuration

Environment variables (all optional except SONAR_API_KEY):

Variable	Default	Purpose
SONAR_API_KEY	(required)	Your sk-sonar-... API key
SONAR_API_BASE	https://api.getsonar.report	Override for staging / self-hosted SONAR
SONAR_API_TIMEOUT	120	Per-request timeout in seconds
SONAR_MCP_LOG_LEVEL	INFO	DEBUG for verbose tool dispatch logs

Example prompts

After configuring, try these in Claude:

"Run a KYB check on Tesco PLC and tell me if anything looks risky."

Claude calls kyb_findings("Tesco PLC") → ~30s → reads back the structured findings → highlights the FCA Register hit, any sanctions matches, director-level red flags.

"Submit a full competitive analysis for Notion and tell me when it's done."

Claude calls competitive_run_submit("Notion") → gets run_id → polls check_report_status every 30s → returns the narrative report.

"How many free trial calls do I have left?"

Claude calls account_balance() → tells you your current balance and how many of your three lifetime free trial calls remain.

How async reports work

The *_run_submit tools return a run_id immediately (in <1s). Claude then needs to call check_report_status(run_id, agent_type) to fetch the result, which is normally ready in 60-180s. Most MCP clients handle this seamlessly — Claude knows from the tool descriptions to poll until status="completed".

The cheaper *_findings tools are synchronous and complete in 30-90s on a single call. Use those when the LLM just needs raw structured data and will do its own analysis.

Verify your install

Use the MCP Inspector to confirm the server starts and tool dispatch works:

SONAR_API_KEY=sk-sonar-... npx @modelcontextprotocol/inspector uvx getsonar-mcp

You should see all 7 tools listed and be able to invoke them with test inputs.

Source

getsonar-mcp is a thin client for the SONAR public API. The source is currently maintained privately; for issues, feature requests, or transport changes, email [e-mail].

Maintainers: see ARCHITECTURE.md for the internal module layout, the OAuth 2.0 flow, and the relationship between the stdio (uvx getsonar-mcp) and HTTP (python -m getsonar_mcp.http_server) transports.

Troubleshooting

Claude says "tool not available" — check claude_desktop_config.json is valid JSON, restart Claude Desktop, then verify uvx --version runs in your terminal.

401 Unauthorized — SONAR_API_KEY is missing or wrong. Verify in the SONAR dashboard at getsonar.report/developer/keys.

402 Payment Required — your 3 free trial calls are used up and your balance is €0. Top up from €5 at getsonar.report/developer/keys, or pick a monthly plan at getsonar.report/settings.

Timeouts — bump SONAR_API_TIMEOUT in your env config. The /run tools can take 3+ minutes for complex KYB subjects.

uvx getsonar-mcp runs an old cached version — uvx aggressively caches resolved environments. Force a refresh with one of:

uvx --refresh getsonar-mcp@<latest>      # pin the version
uv cache clean getsonar-mcp && uvx getsonar-mcp   # wipe + reinstall

TypeError: FastMCP.__init__() got an unexpected keyword argument 'description' — you're on a pre-0.1.6 cached version. Upgrade with uv cache clean getsonar-mcp then uvx getsonar-mcp.

Wrong-entity news in results — make sure you're passing website in your request body. Single-noun brand names ("Stripe", "Apple") collide with unrelated entities on Google News. SONAR drops collisions automatically when the website is supplied.

License

MIT — see LICENSE.