Forage MCP Server Tool Reference

This reference assumes an AI tool is already connected to the Forage MCP (Model Context Protocol) server; see Connect your AI tool for setup. It covers what each tool returns, which one needs your own credentials, and where the server's coverage stops.

Tools

list-endpoints

Returns the full Forage API surface in one call, every path grouped by resource, with a one-line summary of what each method does.

{
  "/o/token/": { "post": "Create an authentication token" },
  "/api/sessions/": { "post": "Create a Fully Hosted Session" },
  "/api/payments/{payment_ref}/capture_payment/": { "post": "Capture an EBT or HSA/FSA Payment" },
  "/api/orders/{order_ref}/refunds/": { "post": "Create a refund for part of an Order", "get": "Retrieve all OrderRefunds for an Order" }
}

The real response lists every path in the API, not just these four.

search-endpoints

Takes a keyword and searches across paths, summaries, and parameters. Searching "refund," for example, returns every refund-related endpoint across Orders and Payments in one call.

[
  {
    "title": "Forage Payments API",
    "endpoints": [
      { "method": "POST", "path": "/api/orders/{order_ref}/refund_all/", "summary": "Create a refund for an entire Order" },
      { "method": "POST", "path": "/api/payments/{payment_ref}/refunds/", "summary": "Create a PaymentRefund" }
    ]
  }
]

A real "refund" search returns more than these two, across both Orders and Payments.

get-endpoint

Returns everything needed to implement one call correctly: the full request and response schema, every named error code with its real message, and a working curl sample. Looking up the capture-payment endpoint (the call that finalizes a payment), for example, returns the complete EBT (Electronic Benefit Transfer) decline-code catalog with customer-facing messages, not just a generic error shape.

curl --request POST \
    --url https://api.sandbox.joinforage.app/api/payments/cc3175bfea/capture_payment/ \
    --header 'Authorization: Bearer <session_token>' \
    --header 'Merchant-Account: <merchant-id>' \
    --header 'Idempotency-Key: <idempotency-key>' \
    --header 'accept: application/json' \
    --header 'content-type: application/json' \
    --data '{
  "capture_amount": 11.98,
  "qualified_healthcare_total": 11.98,
  "qualified_healthcare_subtotal": 11.98,
  "product_list": [
    {
      "gtin": "00041260013003",
      "name": "Sample Healthcare Product",
      "unit_price": 5.99,
      "quantity": 2,
      "eligibility": "hsa_fsa"
    }
  ]
}'

The credentials in that sample (the bearer token, merchant ID, and idempotency key) are placeholders for the capture-payment call itself, not for get-endpoint. Looking up the sample doesn't need your own auth; running the sample against a real payment does.

The full response also includes every named error this endpoint can return, like ebt_error_51 (insufficient funds) with the exact customer-facing message.

get-server-variables

Returns the sandbox and production base URLs, the one piece of environment configuration your AI tool needs to actually address a request somewhere.

[
  {
    "url": "https://{environment}.joinforage.app",
    "variables": {
      "environment": { "default": "api.sandbox", "enum": ["api", "api.sandbox"] }
    }
  }
]

execute-request

Runs a live API call. It's the only one of the five tools that needs authentication: your AI tool has to already hold your own OAuth token, configured in your MCP client. There's no way to test it without real credentials, since it isn't a read-only lookup.

It can run any HTTP method the Forage API supports, including state-changing calls like capturing a payment or issuing a refund, not just lookups. Whatever your OAuth token is allowed to do, this tool can do.

{
  "method": "POST",
  "url": "https://api.sandbox.joinforage.app/api/payments/cc3175bfea/capture_payment/",
  "headers": [
    { "name": "Authorization", "value": "Bearer <your_oauth_token>" }
  ],
  "postData": {
    "mimeType": "application/json",
    "text": "{\"capture_amount\": 11.98}"
  }
}

This shows the shape of a request. The actual response depends on your account and credentials, so there's no fixed example response to show here.

⚠️

This hits real production data

execute-request calls the real Forage API, not a sandboxed copy. A test call through this tool counts as a real request against your account. If a test call charges or refunds something by accident, treat it like any other transaction: use the same cancel, void, or refund endpoint you'd use normally. get-endpoint can look that endpoint up for you.

What this reference doesn't cover

The other four tools work with zero setup beyond connecting the server. Here's the scope of what the server covers, so you know what to expect.

📘

API reference only

The server is scoped to our OpenAPI specification. Questions about frontend SDK steps, integration sequencing, or recommended patterns live in our written guides instead, so a search for a guide-only topic won't return a match here.

There's a second thing worth understanding here too.

⚠️

Cross-check flow-level answers against the guide

Ask an AI tool connected to this server something like "how do I set up a Fully Hosted Checkout in an existing store," and it reasons entirely from the OpenAPI schema, since that's all it has to work with. The answer can look complete on its own, even without the guide-level context it's missing. is_delivery, for example, isn't in the schema's required-fields list, but the Fully Hosted Checkout guide calls it out as required by FNS (the Food and Nutrition Service, the federal agency that oversees SNAP). A flow-level answer reasoning only from the schema can miss that.

Treat a flow-level answer from the MCP server as a starting point, and check Fully Hosted Checkout before you build against it.

To confirm the connection is working, call list-endpoints. A full list of paths back means it's connected; an empty or error response usually means it isn't.

Related

• Connect your AI tool if you haven't already.
• Read How Forage Works, a two-minute overview of the product model.