MCP tools

The nitrograph MCP server exposes four tools. Every MCP-compatible client (Claude Code, Cursor, Windsurf, Claude Desktop, Hermes, Cline, Zed) sees them as first-class tool calls once you connect.

Two ways to connect:

Hosted — register https://api.nitrograph.com/mcp as a remote MCP server in your client (streamable HTTP, stateless). Zero install.
Local — npx nitrograph installs a stdio server and writes it into your client config.

Both paths expose the same tools. The tools are also available as raw HTTP endpoints — see HTTP API.

`nitrograph_discover`

Rank services against a natural-language intent.

Input

| field | type | required | notes | | --------- | ------- | -------- | ------------------------------------------ | | query | string | yes | natural-language description of the task | | limit | integer | no | default 10, max 50 | | filters | object | yes | include every key below; use any for none |

MCP clients must send a complete nested filters object. Do not send root-level filters, {}, null, or max_cost: 0 when you mean "no filter". Use the any sentinel instead:

{
  "query": "lead generation",
  "limit": 10,
  "filters": {
    "rail": "any",
    "max_cost": "any",
    "min_trust": "any",
    "category": "any"
  }
}

Filtered example:

{
  "query": "lead enrichment for SaaS sales",
  "limit": 5,
  "filters": {
    "rail": "mpp",
    "max_cost": "any",
    "min_trust": 70,
    "category": "lead_generation"
  }
}

Returns a ranked list of candidates:

{
  "results": [
    {
      "slug": "apollo",
      "name": "Apollo",
      "rail": "mpp",
      "ranking_score": 0.94,
      "legitimacy_score": 92,
      "rankability_score": 88,
      "similarity": 0.91,
      "match_reason": "strict",
      "cost": { "amount": "0.0056", "currency": "USDC" },
      "map_signals": 12
    }
  ],
  "total_results": 3,
  "strict_count": 3,
  "fallback_count": 0,
  "fallback_used": false,
  "filters_applied": { "rail": "mpp", "max_cost": "any", "min_trust": 70, "category": "lead_generation" }
}

ranking_score is multiplicative: similarity × (legitimacy_score ÷ 100) × (rankability_score ÷ 100), with rankability floored at 0.2 so a strong semantic match still surfaces even for thinly-described services. legitimacy_score (0–100) answers is this a real, alive service? — built from domain age, Wikipedia/HN presence, and live endpoint health. rankability_score (0–100) answers can an agent tell what this does? — built from description specificity and declared schema completeness. map_signals is the number of gotchas and patterns our probe fleet has already mapped for the service.

Every row carries match_reason: strict means the row matched all the filters you passed; fallback means the strict-filter pool was thin, so the row comes from a rail-only fallback. total_results always refers to the strict-filter pool; strict_count and fallback_count break down what is in results.

The formatted tool result is authoritative. Agents should show the returned ranking as-is: do not re-rank, suppress, rename, or promote related_results above the returned results.

`nitrograph_service_detail`

Load the full service map — integration surface plus every gotcha, pattern, and cost contract our probe fleet has mapped for this service.

Input

| field | type | required | notes | | ------ | ------ | -------- | ------------------------------------------ | | slug | string | yes | canonical slug of a service | | task | string | no | current user intent, used to rank endpoints |

Returns

{
  "slug": "apollo",
  "rail": "mpp",
  "cost": { "amount": "0.0056", "currency": "USDC" },
  "call_card": {
    "recommended_endpoint": { "method": "POST", "path": "/v1/people/search" },
    "why": "best match for lead enrichment"
  },
  "endpoints": [ ... ],
  "auth": { ... },
  "gotchas": [
    {
      "id": "07b9",
      "title": "responses wrapped in { success, data }",
      "fix": "unwrap json.data centrally in the client"
    }
  ],
  "patterns": [
    {
      "title": "build list of N decision-makers",
      "steps": [ ... ]
    }
  ]
}

Call this before every first interaction with a service. It is the single biggest latency-and-cost saver in the loop — the map exists because we already paid the debugging tax.

`nitrograph_report_outcome`

Record what happened after your agent actually called a selected service. Do not use this for discovery-only sessions, skipped calls, or payment challenges that were not provider failures. A 402 Payment Required response is usually the x402 payment standard working as designed, not evidence that the service is dead.

Report generalized operational memory only. Do not submit secrets, API keys, bearer tokens, private keys, personal data, confidential customer data, full downstream request payloads, or full downstream responses.

{
  "slug": "apollo",
  "success": false,
  "endpoint": "/v1/people/search",
  "latency_ms": 1240,
  "error_code": "422",
  "diagnosis": "bulk cap rejects batches above 100 records",
  "suggested_fix": "chunk requests into 100-row batches"
}

`nitrograph_report_pattern`

Record a successful reusable workflow after it has worked end-to-end. Use generalized step shapes and parameter templates, not raw customer payloads.

{
  "slug": "apollo",
  "task": "build a list of CRO leads at 50-200 employee SaaS companies",
  "steps": [
    { "step": 1, "endpoint": "/v1/organizations/search", "note": "filter companies by size and industry" },
    { "step": 2, "endpoint": "/v1/people/search", "note": "filter people by seniority and title" }
  ],
  "success": true,
  "cost_usdc": 0.028,
  "latency_ms": 6800
}