MCP tool reference - AgentMuxer

Connect an MCP client to https://mcp.agentmuxer.com/mcp. Every tool runs under your AgentMuxer account, for free discovery as well as paid calls.

Personal clients sign in with OAuth when they connect. The first request answers with a standard HTTP 401 challenge, and clients that support MCP authorization open the browser sign-in for you. See connect your agent.
Applications send their application key as a bearer token: Authorization: Bearer <application key>.

The SDK framework adapters configure this connection for your framework. The examples below are MCP tool arguments, not methods exported by the SDK. Five tools are available. Call an operation directly when you know its provider, path, and inputs. Search when you need a capability, and inspect when its inputs are unclear.

search_offerings

Find API operations when you don’t know which one to call. Searching is free: it never calls a provider or spends credits.

{
  "query": "Search the web for recent TypeScript release notes",
  "limit": 5
}

string

Optional natural-language goal, up to 500 characters. Omit it to browse.

string

Optional provider slug, such as exa, to limit results to one provider.

integer

Optional page size from 1 to 50.

string

An opaque cursor returned by an earlier search. Keep the same query and filters when paging.

"after" | "before"

default:"after"

Page forward or backward with a cursor.

Additional filters

Use arrays for protocols, taskFamilies, tags, trustTiers, capabilityGroups, and useCases, with values from the catalog. Trust tiers are indexed (listed), verified (its interface passed request checks), and benchmarked (also measured in use).

Results include items, ranked by how closely each operation fits your query. Each item names an operation by provider, method, and path, with its name, description, availability (free, priced, or unavailable), and pricing. Each pricing has a readable summary and a kind: free, fixed, components (unit rates), estimate, unknown, or unavailable. Estimates are indicative; the call itself sets the payment terms within your maximum. Use the returned nextCursor or prevCursor to continue. If a cursor is refused with invalid_cursor, search again without it.

inspect_offering

Read the request fields and pricing for one operation. Inspection is free and never calls the provider. It’s optional when you already know the request.

{
  "provider": "exa",
  "path": "/search"
}

string

required

The provider slug from search, such as exa.

string

required

The path template from search, such as /search or /items/{id}.

Optional when the path serves one method. When a path serves several, the response lists the methods to choose from.

Inspection returns the operation with its current pricing and a call-ready view of the request: each field your agent needs for a valid first call, with its type, whether it’s required, and where it goes (pathParams, query, headers, cookies, or body). Where a compact view could change a field’s meaning, the result keeps the complete request description, including parameter serialization and media types. examples holds sample requests when available. Follow the declared types and locations. The listed price describes the operation; the call enforces your maximum charge.

call_offering

Call an API operation by provider and path, within your maximum charge. Supply a new idempotency key for each new logical attempt.

string

required

The provider slug, such as exa.

string

required

The path template, such as /search. Put values for {placeholders} in pathParams.

Optional when the path serves one method. When a path serves several, the refusal lists the methods to choose from.

string

required

A non-empty identifier up to 200 characters, unique across your account. Reuse it for retries, recovery, and accepting terms for the same call.

decimal string

default:"\"1000000\""

Maximum charge in USD credit micros, as a whole-number string. One dollar is "1000000"; ten cents is "100000". "0" permits no positive charge. Without maxCostMicros or maxCost, the maximum is $1.00.

decimal string

The same maximum as a USD string with up to six decimal places, such as "0.25". Supply maxCost or maxCostMicros, not both.

UUID string

Accepts the exact terms of a requires_action result. Copy it from nextAction.acceptTerms and repeat the original arguments unchanged.

Example arguments

Replace the provider, path, and inputs with an operation from search, and supply the inputs that inspection describes.

{
  "provider": "exa",
  "path": "/search",
  "body": { "query": "climate research" },
  "maxCost": "0.10",
  "idempotencyKey": "research-task-unique-call-id"
}

Request inputs

Put provider inputs at the top level of the arguments, next to provider and path.

Field	Use
`pathParams`	Values for the path template’s named parameters
`query`	Named query parameters
`headers`	Headers required by the operation’s interface
`cookies`	Cookies required by the operation’s interface
`body`	Request body matching the inspected schema
`querystring`, `contentType`	Only when specified by the interface
`binaryBody`	Base64-encoded raw content as `{ base64 }`
`multipartFiles`	Files grouped by field name, each with `base64`, `filename`, and optional `contentType`

Keep your AgentMuxer application key out of tool inputs. Authentication belongs on the MCP connection.

Purchases and retries

Call within your maximum

Submit the operation, inputs, an idempotency key, and optionally a maximum. Account balance, application spending limits, and payment confirmation still apply. Only a 2xx provider response bills, and it bills exactly once at the accepted price.

Accept higher terms explicitly

When the price is above your maximum, the result has kind: "requires_action" with approvalKind: "agent", the exact terms (costMicros and expiresAt), and nextAction.acceptTerms. To accept, repeat the original arguments unchanged, including the key, adding acceptTerms. If you decline, stop. Acceptance works within your spending limits.

Confirm as a person when your account requires it

When payment confirmation is required, AgentMuxer asks the person through the client’s confirmation prompt, and the call continues after approval. A client without confirmation prompts receives an approval_required refusal, and nothing is charged. See billing and approvals.

Recover with the original key

A replay with the same key and arguments returns the existing result without another execution or charge. After a timeout, a lost response, or a pending result, call get_invocation with the original key. Start a new call with a new key only when you deliberately want a new purchase.

Results

Every result has a kind. Results for a known call also include invocationId, idempotencyKey, operation, and billing.

"responded" | "pending" | "requires_action" | "refused"

responded: the provider answered. pending: the outcome isn’t final yet (reason is executing, reconciling, or outcome_unknown); recover with get_invocation. requires_action: the call needs accepted terms or a person’s confirmation. refused: nothing was bought.

object

For responded results: the provider’s HTTP status and body. A provider non-2xx is still responded, and it doesn’t bill. A body that has expired or wasn’t kept has bodyUnavailable instead.

boolean

For responded results: whether this is a replay of an existing call.

"pending" | "finalized"

Whether accounting has finalized. A pending charge is not a reason to call again.

decimal string

The amount billed in USD credit micros, when known. billing.acceptedCostMicros is the accepted price.

decimal string

Your account balance, when present in the response.

Refusals are results, not protocol errors. refusedBy names the refusing subsystem (auth, policy, balance, budget, cap, resolution, request, or listing), and reason, message, and optional diagnostics explain why. Follow nextAction when present: an insufficient-balance refusal carries nextAction: { kind: "top_up", url } for the account owner, and request errors name the field to correct. Invalid arguments return an error that names the failing field. See troubleshooting before retrying. A provider response, including HTTP 202, reports the provider’s answer; a provider job may continue after it.

get_invocation

Recover a lost response or check a pending call. Lookup is free: it never calls the provider, reserves credits, or resumes a purchase.

{
  "idempotencyKey": "research-task-unique-call-id"
}

UUID string

The invocationId from an earlier result.

string

The original idempotency key of the call.

Supply exactly one of the two. The result has the same shape as a call_offering result. For a pending call, look it up again later. If the lookup returns invocation_not_found, repeat the original call_offering arguments with the same key; the key ensures the call runs at most once.

report_outcome

Report whether an invocation helped with the task. Reporting is optional, and this feedback is separate from the provider’s HTTP response and billing.

UUID string

required

The invocation identifier returned by the call.

"succeeded" | "failed" | "not-useful"

required

Choose the result that describes the task outcome.

string

Optional explanation up to 1,000 characters. Leave out secrets.

The response reports accepted and duplicate. Your account records one report per invocation; repeated reports are acknowledged without recording another.

Billing, limits, and approvals

See when charges apply and how framework permissions differ from payment confirmation.

​search_offerings

​inspect_offering

​call_offering

​Example arguments

​Request inputs

​Purchases and retries

​Results

​get_invocation

​report_outcome

Billing, limits, and approvals

search_offerings

inspect_offering

call_offering

Example arguments

Request inputs

Purchases and retries

Results

get_invocation

report_outcome