nitrograph

name	nitrograph
description	Use Nitrograph when the user asks to find, search for, compare, price, or inspect an API or service that can perform a task — including paid and agent-payable services on x402, MPP, and similar rails. Also covers reading a service's call card before calling it, and reporting whether a call worked.

Nitrograph

Nitrograph is a discovery layer for agent-usable services. Use it to find APIs for a task, compare ranked options, inspect invocation details, and report whether a service call worked.

Nitrograph tells you what to call and how. It does not make the call for you — use your own HTTP capability, or the user's code, with the call card it returns.

Surface Selection

1. Use the Nitrograph MCP tools: nitrograph_discover, then nitrograph_service_detail.
2. In Node projects the user is writing, the same registry is available as a TypeScript library: import { Nitrograph } from 'nitrograph'.
3. In other runtimes, the registry is available over plain HTTP.

Discovery Workflow

1. Run discovery with the user's task as a natural-language query.
2. Omit filters unless the user explicitly requested a rail, category, or price ceiling.
3. Present results as the ranked, high-confidence recommendations. 3a. If the user asks for more options, re-run discovery with offset advanced by the number already shown, rather than re-running the same query. The response reports has_more.
4. Keep related_results separate as lower-confidence fallbacks. Do not promote them into recommendations.
5. Do not reorder, regroup, or add your own "notably absent" recommendations. Nitrograph ranking is authoritative.
6. Before calling a service, fetch service detail for the selected service using the stable slug; include the original user task in the task argument when the tool supports it.
7. Use service_detail.call_card as the executable invocation plan. It tells you the recommended endpoint for the selected task, endpoint options, request schemas, payment behavior, gotchas, proven patterns, and when to report outcomes.
8. Use service detail/OpenAPI as the schema source of truth for callable paths, methods, and request bodies.
9. After a paid service actually runs, report the outcome with success/failure, endpoint, latency, and a concise failure diagnosis when applicable.

Critical Invocation Rules

• Do not invent endpoints from discover results.
• Do not include filters: {} or default filters.
• Do not send rail: "" or category: "". Omit those fields when unused.
• Do not send max_cost: 0 for "no cost filter." max_cost: 0 means free-only and is rejected; omit max_cost unless the user asked for a price ceiling.
• If Nitrograph says "No services matched" for a broad/common commercial query, immediately inspect filters_applied before concluding no services exist.
• Treat discover route or route.call as a routing preview only. It may be inferred or less specific than service detail.
• Treat call_card as the selected service's call plan. If call_card.invocation.recommended_endpoint is present, start there unless it clearly conflicts with the user's task.
• Use slug for programmatic follow-up calls. display_slug is for human-readable output.
• If service detail includes openapi.paths, prefer those paths and methods over the discover preview.
• If a call fails, report the actual root cause. Do not report generic "API failed" diagnoses.
• If Nitrograph reports that the search limit was reached, tell the user and stop searching. Do not attempt to work around the limit.
• A 402 Payment Required from a third-party provider means that provider has not run the request yet. It is a payment challenge, not a service failure, and must not be reported as one.
• Do not send secrets, private keys, bearer tokens, passwords, raw customer payloads, confidential customer data, or full downstream service responses to Nitrograph.
• Keep outcome reports and pattern reports concise and operational. Report generalized diagnoses, fixes, and reusable templates rather than sensitive raw data.

MCP Tool Use

The server exposes five tools.

Tool	Use it for
nitrograph_discover	Search and rank services for a task. Supports limit, offset, and optional filters.
nitrograph_service_detail	Full call card for one service by slug.
nitrograph_report_outcome	Record success/failure of a call after it ran.
nitrograph_report_pattern	Record a reusable multi-step workflow that worked.
nitrograph_session_status	Check remaining search quota without consuming any.

Nitrograph returns the information needed to call a service. It does not make the call. Use the model's own HTTP capability, or the user's own code, to call the provider directly using the call card.

When calling nitrograph_discover, the tool's returned markdown display is authoritative user-facing output. Return it as-is when the user asked to see search results. Do not paraphrase or regroup it.

Use nitrograph_service_detail after discovery when the user wants to call, inspect, compare deeply, or implement against a service. Pass the original task/query as task so Nitrograph can rank endpoints for the selected service.

Use nitrograph_session_status before a batch of searches to check queries_remaining, or when a search reports that a limit was reached. It does not consume quota. If the limit is reached, tell the user searches are temporarily unavailable and stop — do not retry in a loop.

Use nitrograph_report_outcome only after a service actually ran and produced a success or a genuine provider failure. Do not call it for 402 Payment Required or payment challenges.

{
  "slug": "apollo",
  "success": false,
  "endpoint": "/v1/people/search",
  "latency_ms": 1200,
  "error_code": "422",
  "diagnosis": "The endpoint required a company domain but only a company name was supplied.",
  "suggested_fix": "Resolve the company domain before calling the people search endpoint."
}

Use nitrograph_report_pattern only for genuine reusable successful workflows.

TypeScript Harness

import { Nitrograph } from 'nitrograph';

const ng = new Nitrograph();

const { results, related_results } = await ng.discover('lead generation', {
  limit: 10,
});

const service = results[0];
const detail = await ng.serviceDetail(service.slug, {
  task: 'lead generation',
});

const quota = await ng.sessionStatus();

Raw HTTP

Discover:

curl -sX POST https://api.nitrograph.com/v1/discover \
  -H 'content-type: application/json' \
  -d '{"query":"lead generation","limit":10}'

Service detail:

curl -s https://api.nitrograph.com/v1/service/apollo

Report outcome:

curl -sX POST https://api.nitrograph.com/v1/service/apollo/report-outcome \
  -H 'content-type: application/json' \
  -d '{"success":true,"endpoint":"/v1/people/search","latency_ms":350}'

Result Interpretation

• results: primary recommendations.
• related_results: semantic fallbacks only.
• match_strength: "strong": usable as a recommendation.
• match_strength: "related": show only under related/fallbacks.
• healthy: false or recent last_probe_error: warn the user before invoking.
• cost_per_call/cost: show before spending when available.
• has_more: true: more ranked results exist; fetch them with offset, not by re-querying.
• slug vs display_slug: pass slug to other tools; show display_slug to the user.

Filters

All filters are optional and live under filters. Send only what the user asked for.

• rail: payment rail, e.g. x402, mpp, stripe.
• category: a value from GET /v1/categories. Do not invent one — fetch the list if unsure.
• max_cost: price ceiling in USD per call. Never send 0 to mean "no ceiling"; 0 means free-only.
• min_trust: trust floor.

Docs

Full agent docs: https://nitrograph.com/llms-full.txt Privacy: https://nitrograph.com/privacy Terms: https://nitrograph.com/terms