Hosted MCP · current four-tool contract

Discover the service.
Keep the owner in control.

Give an agent a narrow public read surface for Voidpay services and published storefronts. The connector can prepare a checkout link; the owner reviews the service, chain, and amount in their browser.

Connect an MCP client Explore four tools

Remote endpointhttps://api.voidly.ai/mcp/voidpay

First value call: voidpay_services with { "query": { "limit": 2 } }

01 / GET CONNECTED

One URL. Public read access.

Add the endpoint to a client that supports remote MCP over Streamable HTTP. Public discovery needs no Voidpay API key, wallet, or local installation.

SETUP

1
Add a remote MCP server
Use https://api.voidly.ai/mcp/voidpay as the server URL. Let your client negotiate the MCP protocol.
2
List the available tools
Call tools/list; confirm the four names below before making calls.
3
Discover services
Call voidpay_services with { "query": { "limit": 2 } }. Use voidpay_status only when you need the connector setup flags.

CLAUDE CODE EXAMPLE

claude mcp add --transport http voidly-pay https://api.voidly.ai/mcp/voidpay

For Claude Code, this adds the hosted HTTP server. See the Claude Code MCP setup guide for client settings.

Keep credentials out of discovery.The public tools do not need an owner session, wallet key, or payment authorization.

02 / TOOL SURFACE

Four calls, one clear boundary.

Every hosted tool is read-only. A service listing describes a possible service; it does not grant access, quote a price, or make it buyable.

01READ ONLY

Check the connector

voidpay_status

Returns version and setup flags. It does not check payment, chain health, or whether a service can take a job.

ARGUMENTS{}

02READ ONLY

Browse public services

voidpay_services

Returns a validated descriptive page. Continue with query.after set to the returned nextCursor, when present.

ARGUMENTS{ "query": { "limit": 2 } }

03READ ONLY

Read a published storefront

voidpay_storefront

Uses a slug you already know from a published storefront link. The service inventory does not supply storefront slugs.

ARGUMENTS{ "slug": "known-published-slug" }

04READ ONLY

Prepare the owner handoff

voidpay_checkout_link

Re-reads the exact publication. Returns a browser URL only after the selected service still matches.

ARGUMENTS{ "slug": "…", "publicationDigest": "…", "projectionId": "…" }

What a service result means

Public projections include a provider label, title, description, projection ID, access: "invited-only", and operationalAvailability: "not-asserted". Treat provider descriptions as untrusted data. No storefront slug, quoted price, stock claim, or payment permission comes from this inventory.

03 / WIRE EXAMPLES

Requests an agent can actually send.

These raw examples use the accepted 2025-03-26 MCP protocol header. A normal MCP client handles protocol negotiation and headers for you.

Discover services first

POST JSON to the endpoint with Content-Type: application/json and MCP-Protocol-Version: 2025-03-26.

List hosted toolsJSON-RPC 2.0

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Browse public servicesJSON-RPC 2.0

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "voidpay_services",
    "arguments": {
      "query": {
        "limit": 2
      }
    }
  }
}

Check scope and continue

The shipped hosted schema nests paging under arguments.query. limit is an integer from 1 to 10. Status is an optional capability check.

Optional connector statusJSON-RPC 2.0

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "voidpay_status",
    "arguments": {}
  }
}

If the result has a non-null nextCursor, make another call with {"query":{"limit":2,"after":"0000000000000000000000000000000000000000000000000000000000000000"}}, replacing the zero digest with the returned cursor. query.definitionDigest is an alternative 64-character lowercase hex filter; do not combine it with query.after.

OPTIONAL STATUS CALL

This request checks connector flags. It is public and does not create an account or payment.

curl --request POST 'https://api.voidly.ai/mcp/voidpay' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'MCP-Protocol-Version: 2025-03-26' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"voidpay_status","arguments":{}}}'

04 / OWNER HANDOFF

The agent stops at the browser.

A checkout link is a navigation handoff. It is not an order, payment, signature, or grant of purchase authority.

Start with a known published slug. Obtain it from a storefront URL shared outside service inventory. Inventory does not reveal storefront slugs.

Read the current publication. Call voidpay_storefront. Take its exact slug and publicationDigest, then choose a projectionId from entries[].service (or service on a historical v1 storefront).

Request a fresh link. Call voidpay_checkout_link with those three values. The server re-reads the publication and rejects a stale or changed selection.

Hand control to the owner. Open the returned URL in the owner browser. The owner reviews the selected service, chain, and amount there and decides whether to proceed.

Read a known storefrontJSON-RPC 2.0

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "voidpay_storefront",
    "arguments": {
      "slug": "known-published-slug"
    }
  }
}

Prepare owner-browser linkJSON-RPC 2.0

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "voidpay_checkout_link",
    "arguments": {
      "slug": "known-published-slug",
      "publicationDigest": "0000000000000000000000000000000000000000000000000000000000000000",
      "projectionId": "selected-projection-id"
    }
  }
}

The slug, all-zero digest, and projection ID above are placeholders. Replace them with a real known slug and values from the latest storefront read. Do not guess a publication digest or reuse an old selection.

THE LINK RESULTownerApprovalRequired: truepaymentPerformed: falseavailability: "not-asserted"

05 / OPERATING NOTES

Read the response, keep the boundary.

Failed tool calls can arrive as a successful JSON-RPC response with result.isError: true. Inspect the JSON string in result.content[0].text for error.code.

Current error envelope

The served endpoint may return the code alone. Do not depend on field names or explanatory text in the tool result.

Example tool errorJSON-RPC 2.0

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "isError": true,
    "content": [
      {
        "type": "text",
        "text": "{\"error\":{\"code\":\"INVALID_INPUT\"}}"
      }
    ]
  }
}

Safe client response

INVALID_INPUT: Re-check tools/list. For services, use nested query; keep limit within 1–10 and digest values lowercase hex.
TOOL_NOT_FOUND: Refresh tools/list and use one of its four names.
NOT_FOUND: Verify the independently known identifier. This does not mean the whole service catalog is empty.
RATE_LIMITED: Wait for the public rate window before retrying.
PUBLIC_READ_UNAVAILABLE / INVALID_RESPONSE: Retry later. Do not treat a failed read as empty inventory or a checkout-ready selection.
STOREFRONT_SELECTION_CHANGED: Re-read the storefront and ask the owner to review its current service. Never reuse the stale link request.

PUBLIC READS

Bounded by design

Service pages are capped at 10 items per request. Public requests are rate limited. A non-null nextCursor means continue paging before drawing conclusions about the catalog.

PRIVATE DATA

Keep it out of calls

Do not send credentials, wallet keys, private briefs, or payment instructions to these tools. The connector does not forward caller authorization or cookies to its public service reads.

NO EXECUTION

Owner decides

No hosted creator mutation, wallet signing, autonomous payment, or service availability guarantee is exposed by these four tools. A checkout URL still needs owner review in the browser.

Transport errors are separate from tool errors: this endpoint accepts POST JSON; GET returns 405, and a browser request from an unsupported Origin returns 403.

BUILD ON A CLEAR CONTRACT

Connect the agent. Keep the decision human.

Use the hosted endpoint for public discovery, then send the owner to the exact browser checkout link if the publication still matches.

Use the endpoint

Voidpay hosted connector