MCP tools

The nitrograph MCP server exposes seven tools: nitrograph_discover, nitrograph_service_detail, nitrograph_invoke_service, nitrograph_authenticate, nitrograph_report_outcome, nitrograph_report_pattern, and nitrograph_session_status. 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

filters is optional - omit the object entirely when the user asked for no constraints, and include only the key(s) they asked for. max_cost is numeric USD (do not send 0 - that means free-only); rail is x402, mpp, stripe, or none. Do not send root-level filters or an "any" sentinel - the live schema rejects them:

{ "query": "lead generation", "limit": 10 }

Filtered example (only the keys the user asked for):

{
  "query": "lead enrichment for SaaS sales",
  "limit": 5,
  "filters": {
    "rail": "mpp",
    "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

Returns

{
  "slug": "apollo",
  "rail": "mpp",
  "cost": { "amount": "0.0056", "currency": "USDC" },
  "call_card": {
    "recommended_endpoint": { "method": "POST", "path": "/apollo/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": "/apollo/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": "/apollo/people-search", "note": "filter people by seniority and title" }
  ],
  "success": true,
  "cost_usdc": 0.028,
  "latency_ms": 6800
}

nitrograph_invoke_service

Call a service through Nitrograph instead of directly. Nitrograph quotes the price, holds credits, pays the provider over x402, validates the response, and settles only on a validated pass — failed work is refunded. Status, latency, endpoint, and payment state are captured automatically, so a separate report_outcome call is unnecessary for invoked calls.

Requires a funded credits account and agent-scope token (early access, OAuth-capable hosts can simply connect and authenticate (OAuth 2.1 + PKCE, discovery at /.well-known/oauth-protected-resource); otherwise self-serve - sign in at nitrograph.com/login or let the agent pair at nitrograph.com/pair). See POST /v1/invoke for the full semantics, including intent-based routing to certified suppliers.

First certified call free: pairing or OAuth connect seeds a one-time $1 certified-only credit, so an agent's first certified invoke settles with no top-up.

nitrograph_session_status

Check the remaining free-tier quota for the current session without consuming any of it.