> Feedback: If these docs are stale, missing, or confusing, post sanitized feedback to `https://docs.tempo.xyz/api/feedback` with `source: "mcp"`, a short `message`, and any relevant `toolName`, `relatedResource`, or `client`. # Discover MPP services MPP service discovery helps agents find paid APIs before they make a request. Use it to rank services for a task, compare payment offers, inspect endpoint metadata, and build the next HTTP request. Discovery is advisory. The runtime `402 Payment Required` challenge from the target service is always the authoritative source of current payment terms. ## Discovery surfaces | Surface | URL | Use it for | | --- | --- | --- | | Web directory | [`https://mpp.dev/services`](https://mpp.dev/services) | Browse live services, categories, providers, endpoints, and examples. | | Public catalog API | [`https://mpp.dev/api/services`](https://mpp.dev/api/services) | Fetch the JSON catalog directly from scripts, CLIs, or custom agents. | | Services MCP | [`https://mpp.dev/mcp/services`](https://mpp.dev/mcp/services) | Let an MCP-capable agent rank services, inspect offers, get usage recipes, and fetch advisory OpenAPI summaries. | | Protocol reference | [`https://mpp.dev/advanced/discovery`](https://mpp.dev/advanced/discovery) | Learn how service providers publish discovery metadata. | Use this page as the agent-facing setup and recipe guide. Use `mpp.dev` for the live catalog, protocol reference, and service-provider discovery docs. The services MCP server is read-only. It does not register services, execute payments, sign transactions, or proxy paid API calls. ## Connect over MCP Use the Streamable HTTP endpoint: ```text https://mpp.dev/mcp/services ``` :::code-group ```bash [Claude Code] claude mcp add --transport http mpp-services https://mpp.dev/mcp/services ``` ```bash [Codex] codex mcp add mpp-services --url https://mpp.dev/mcp/services ``` ```bash [Amp] amp mcp add --transport http mpp-services https://mpp.dev/mcp/services ``` ```json [Cursor] { "mcpServers": { "mpp-services": { "url": "https://mpp.dev/mcp/services" } } } ``` ```json [Manual] { "mcpServers": { "mpp-services": { "url": "https://mpp.dev/mcp/services" } } } ``` ::: For AWS AgentCore, Bedrock agents, or another managed agent runtime, configure a remote MCP server with Streamable HTTP transport, no authentication, and the endpoint above. ## Smoke test with Inspector Use the MCP Inspector when you want to verify the server from the same environment as your agent: ```bash npx -y @modelcontextprotocol/inspector \ --cli \ --transport http \ --server-url https://mpp.dev/mcp/services ``` You can also smoke test with plain JSON-RPC: ```bash curl https://mpp.dev/mcp/services \ -H 'content-type: application/json' \ -H 'accept: application/json, text/event-stream' \ --data '{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": { "name": "my-agent", "version": "1.0.0" } } }' ``` Expected result: `serverInfo.name` is `mpp-services-mcp`, `instructions` mention that discovery is advisory, and `tools/list` includes `recommend_services`, `get_usage_recipe`, `search_offers`, and `get_catalog_status`. ## Recommended agent workflow ::::steps ### Rank services for the task Start with `recommend_services` when the agent has a task but not a provider. ```json { "name": "recommend_services", "arguments": { "task": "send a transactional email from an agent", "constraints": { "category": "ai", "method": "tempo", "limit": 5 } } } ``` The response includes ranked services, matched task terms, reasons, top payment offers, and suggested next MCP calls. ### Get a usage recipe After choosing a service, call `get_usage_recipe` to get payable endpoint candidates, target URLs, and the HTTP steps the agent should follow. ```json { "name": "get_usage_recipe", "arguments": { "service": "agentmail" } } ``` Use `route` when the agent already knows the endpoint: ```json { "name": "get_usage_recipe", "arguments": { "service": "agentmail", "route": "POST /v0/inboxes" } } ``` ### Inspect payment offers Use `search_offers` or `get_offers` when the agent needs endpoint-level payment terms. ```json { "name": "search_offers", "arguments": { "query": "web search", "category": "search", "method": "tempo", "dynamic": false, "limit": 10 } } ``` ### Inspect the API shape Fetch an advisory OpenAPI summary or registry-derived endpoint view before constructing the request body. ```json { "name": "get_openapi", "arguments": { "service": "agentmail" } } ``` ### Make the paid request Call the target service directly with an MPP-capable client such as [`tempo request`](/docs/cli/request). The service returns a `402` challenge if payment is required, and the client pays and retries. ```bash tempo request -X POST \ --json '{"prompt":"a sunset over the ocean"}' \ https://fal.mpp.tempo.xyz/fal-ai/flux/dev ``` :::warning The MCP server only helps with discovery and planning. The target service's runtime `402` challenge controls the final amount, currency, recipient, method, and credential flow. ::: :::: ## Example recipes | Agent task | Start with | Then call | | --- | --- | --- | | Send email or create an agent inbox | `recommend_services` with `task: "send email from an agent"` | `get_usage_recipe` for the selected service, then `get_openapi` | | Find an LLM or image model endpoint | `recommend_services` with `category: "ai"` | `search_offers` to compare fixed vs dynamic pricing | | Search the web or crawl pages | `recommend_services` with `category: "search"` | `get_usage_recipe` for the chosen search provider | | Map a `402` recipient back to services | `get_services_by_recipient` | `get_offers` and `get_service` for the matching provider | | Build custom catalog analytics | `get_facets` and `get_catalog_status` | Fetch [`https://mpp.dev/api/services`](https://mpp.dev/api/services) directly | ## Agent prompts Give your agent a task and tell it to use the services MCP server first: ```txt Use the mpp-services MCP server to find a paid API for sending email from an agent. Rank options with recommend_services, inspect the best service with get_usage_recipe, then tell me the target endpoint and what the runtime 402 challenge will confirm. Do not execute payment. ``` ```txt Use the mpp-services MCP server to find AI model APIs that support Tempo payments. Compare endpoint offers, prefer active services with OpenAPI metadata, and summarize which route I should call with tempo request. Discovery is advisory. ``` ```txt Use the mpp-services MCP server to find web search or crawl APIs. Show the top three services, why each matched, whether pricing is fixed or dynamic, and the next MCP tool call you would make before constructing the HTTP request. ``` ## MCP tools | Tool | Purpose | | --- | --- | | `list_services` | List catalog services with id, name, URL, categories, integration, status, and description. | | `search_services` | Search services by text query and exact filters. | | `search_offers` | Search endpoint-level payment offers by task, method, currency, amount, recipient, and category. | | `recommend_services` | Rank paid API services for a natural-language agent task with optional exact constraints. | | `get_usage_recipe` | Turn a selected service into endpoint candidates, follow-up MCP calls, and target HTTP/`402` steps. | | `get_facets` | Discover valid filter values and counts before narrowing a search. | | `get_services_by_recipient` | Identify services that publish offers for a payment recipient. | | `get_catalog_status` | Inspect catalog version, source URL, cache age, refresh time, and service count. | | `get_service` | Fetch the full service record by id or name. | | `get_offers` | Fetch payment offers for one service, optionally filtered by route. | | `get_openapi` | Fetch a live OpenAPI summary when available, otherwise return the registry endpoint view. | ## Choosing a discovery surface Use the web directory when a human is exploring the catalog. Use the public API when you are building your own service browser, CLI, or analytics job. Use the MCP server when an agent needs tool-callable discovery inside its planning loop. For execution, call services directly with [`tempo request`](/docs/cli/request), the [MPP client quickstart](/docs/guide/machine-payments/client), or another MPP-capable client. Discovery narrows the choice; the service's runtime `402` challenge confirms the exact payment terms. ## Next steps