Merge Unified's Ramp integration Merge Agent Handler's Ramp MCP server

Connect your AI Agents to Ramp in minutes

Merge lets you securely connect your agents to Ramp and thousands of tools instantly

Start building for free

Read docs

Ramp

Learn more about Merge Agent Handler

Available tools

list_gl_accounts

List Ramp GL (General Ledger) accounts for accounting integration. Returns account names, codes, and classifications. Supports cursor-based pagination.

list_vendors

List Ramp vendors for bill pay. Returns vendor names, contact info, and default payment methods. Supports cursor-based pagination.

list_bills

List Ramp bills. Filters: entity, vendor, purchase order, payment, invoice number; approvalstatus (APPROVED/INITIALIZED/PENDING/REJECTED/TERMINATED), paymentstatus (OPEN/PAID), finer status_summaries; amount range; issued/due/created/paid/payment date ranges; sync and archived flags. Approval and payment are independent. Amounts are major units (500.00 = $500). Cursor pagination.

get_bill

Get a specific Ramp bill by ID with full details including line items, vendor info, and payment method.

create_bill

Create a new Ramp bill for bill pay. Requires vendorid, entityid, invoicenumber, issuedat, dueat and invoicecurrency, plus exactly one of amount or lineitems. Use listvendors for vendor IDs and list_entities for entity IDs. Optionally include a memo.

update_bill

Update an existing Ramp bill. Only approved bills can be updated. Can modify invoice number, issue date, due date, memo and line items. To change the bill total, send lineitems -- Ramp derives the amount from them and has no separate amount field. Use listbills to find bill IDs.

get_business

Get the Ramp business profile including business name, settings, and integration status.

get_business_balance

Get the Ramp business balance including current balance, statement balance, credit limit, and available credit.

get_bank_account

Get a specific Ramp bank account by ID with account type, verification status, and details.

list_cards

List Ramp cards with filtering by user, entity, card program, physical/virtual type, and state (ACTIVE, SUSPENDED, TERMINATED). Supports cursor-based pagination.

get_card

Get a specific Ramp card by ID with full details including spend limits, spending restrictions, and cardholder info.

create_virtual_card

Create a new Ramp virtual card. This is an async operation that returns a task ID. Use getdeferredtask_status to check completion.

create_physical_card

Create a new Ramp physical card. Requires shipping address. This is an async operation that returns a task ID. Use getdeferredtask_status to check completion.

get_deferred_task_status

Check the status of an async/deferred Ramp operation (card creation, suspension, etc.). Returns task status and result data when completed.

update_card

Update a Ramp card's display name, spend limit, or spending restrictions.

suspend_card

Suspend a Ramp card. This is an async operation that returns a task ID. The card will be temporarily disabled.

unsuspend_card

Unsuspend/reactivate a suspended Ramp card. This is an async operation that returns a task ID.

list_departments

List all Ramp departments/cost centers with their entity assignments and hierarchy. Supports cursor-based pagination.

list_entities

List all Ramp business entities for multi-entity businesses. Returns entity names, addresses, and primary entity designation. Supports cursor-based pagination.

get_entity

Get a specific Ramp business entity by ID with full details including address and phone.

list_limits

List Ramp spending limits/policies with filtering by user, card, department, and entity. Returns limit amounts, intervals, and usage. Supports cursor-based pagination.

get_limit

Get a specific Ramp spending limit by ID with full details including amount, interval, restrictions, and current usage.

list_purchase_orders

List Ramp purchase orders with filtering by entity, creation source, receipt status, spend request, external/remote ID, three-way-match, and creation date range. Supports cursor-based pagination. Archived purchase orders are excluded by default.

get_purchase_order

Get a specific Ramp purchase order by ID with full details including line items, accounting field selections, vendor, amounts, attached bills and transactions, and receipt status.

create_purchase_order

Create a new Ramp purchase order. Requires entity ID and at least one line item (each with unitprice and unitquantity). Optionally include vendor, memo, purchase order number, owner, dates, net payment terms, and accounting field selections.

update_purchase_order

Update an existing Ramp purchase order. Can modify memo, spend start/end dates, accounting field selections, and the default withholding rate.

archive_purchase_order

Archive a Ramp purchase order, optionally with a reason. Archived purchase orders are excluded from list results by default.

add_purchase_order_line_items

Add one or more line items to an existing Ramp purchase order. Each line item requires unitprice and unitquantity. Existing line items are preserved.

update_purchase_order_line_item

Update a single line item on a Ramp purchase order. Can modify description, unit price, unit quantity, accounting field selections, and withholding rate.

delete_purchase_order_line_item

Delete a single line item from a Ramp purchase order. Returns the updated purchase order.

list_reimbursements

List Ramp reimbursement requests with filtering by user and status (PENDING, APPROVED, REJECTED, REIMBURSED). Supports cursor-based pagination.

get_reimbursement

Get a specific Ramp reimbursement by ID with full details including receipts, accountingfieldselections, state, and the entityamount/merchantamount/payeeamount objects. Use listreimbursements to find reimbursement IDs.

list_transactions

List Ramp card transactions with filtering by date range, card ID, user ID, department ID, amount range, and transaction state (PENDING, CLEARED, DECLINED). Supports cursor-based pagination.

get_transaction

Get a specific Ramp transaction by ID with full details including receipts, memo, merchant info, and accounting categories.

list_cashbacks

List Ramp cashback/rewards earned on transactions. Supports cursor-based pagination.

list_users

List Ramp users with filtering by department, location, role (ADMIN, OWNER, USER, BOOKKEEPER), status, and entity. Supports cursor-based pagination.

get_user

Get a specific Ramp user by ID with full profile including associated cards, spending limits, department, and manager info.

validate_credential

Validate Ramp credentials. Verifies credentials during setup.

View all tools by creating a free account See more tools

How to set up Merge Agent Handler

In an mcp.json file, add the configuration below, and restart Cursor.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5      "headers": {
6        "Authorization": "Bearer yMt*****"
7      }
8    }
9  }
10}
11

Copy Code

Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.

Make sure Claude is using the Node v20+.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "mcp-remote@latest",
8        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9        "--header",
10        "Authorization: Bearer ${AUTH_TOKEN}"
11      ],
12      "env": {
13        "AUTH_TOKEN": "yMt*****"
14      }
15    }
16  }
17}

Copy Code

Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.

Learn more in the official documentation ↗

1{
2    "mcpServers": {
3      "agent-handler": {
4        "command": "npx",
5        "args": [
6          "-y",
7          "mcp-remote@latest",
8          "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9          "--header",
10          "Authorization: Bearer ${AUTH_TOKEN}"
11        ],
12        "env": {
13          "AUTH_TOKEN": "<ah-production-access-key>"
14        }
15      }
16    }
17  }

Copy Code

In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".

You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.

Learn more in the official documentation ↗

1{
2  "inputs": [
3    {
4      "type": "promptString",
5      "id": "agent-handler-auth",
6      "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7      "password": true
8    }
9  ],
10  "servers": {
11    "agent-handler": {
12      "type": "stdio",
13      "command": "npx",
14      "args": [
15        "-y",
16        "mcp-remote@latest",
17        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18        "--header",
19        "Authorization: Bearer ${input:agent-handler-auth}"
20      ]
21    }
22  }
23}

Copy Code

FAQs on using Merge's Ramp MCP server

What is a Ramp MCP server?

It’s an MCP server that lets you access data and functionality from Ramp via tools. Your agents can call these tools to create virtual cards, fetch details on specific vendors, update bills, and more.

Ramp offers its own MCP server. You can also access Ramp MCP servers from 3rd-party platforms, like Merge Agent Handler.

What are some impactful ways to use Ramp’s MCP server?

Here are some of the top ways your agents can use a Ramp MCP server?

Auto-categorize spend and keep your books clean: Use transaction-level context (e.g., merchants, memos, category rules) to suggest or apply consistent categorizations, and flag uncategorized items before close

Week/month close copilot: Pull the latest card charges, reimbursements, and bills, then generate a close checklist, highlight anomalies, and compile questions for budget owners

Budget vs actual monitoring in real time: Continuously compare spend to budgets by team, vendor, or category, and surface “at-risk” areas early with a short narrative summary

Vendor spend insights and consolidation: Identify duplicate tools and overlapping vendors across teams, quantify total annualized spend by vendor, and recommend consolidation candidates

Contract renewal and price-change surveillance: Tie transactions to vendors and renewal dates (from your contract system), then alert when spend patterns change ahead of renewal negotiations

Policy enforcement at the point of decision: Before a purchase is approved, check policy (i.e., category limits, merchant restrictions, per-role rules) and recommend the right approval path or cheaper compliant alternatives

What makes Merge Agent Handler’s Ramp MCP server better than alternative Ramp MCP servers?

Merge Agent Handler’s Ramp server offers:

Built-in authentication and credential handling: The platform handles authentication, credential management, and the user auth flow through Merge Link, so you don’t need to build those pieces around the Ramp connector yourself

Maintained, extensible connectors: The Ramp connector is maintained, tested, and extensible, allowing you to use it for your exact agentic use cases

Real-time observability: Merge Agent Handler provides tool-call logging and API request logging, and logs can be searched by registered user, Tool Pack, connector, and more

Security controls on tool inputs and outputs: Merge’s security gateway scans inbound and outbound tool traffic for sensitive data, and supports configurable actions and custom rules rather than leaving this entirely to the MCP client or application layer

Scoped tool access and pre-production testing: Tool Packs let you restrict which Ramp tools an agent can use, and the Evaluation Suite plus Tool Pack Tester let you validate behavior before production rollout

Can I set custom security rules for Ramp tool calls in Merge Agent Handler?

Yes, Merge Agent Handler lets you activate security rules and configure actions for both inbound and outbound traffic. Here are some rules you can set:

Step-up approval for money movement: Block or require human approval for actions that move money or change high-risk settings, like payments, refunds, issuing cards, limit changes, or bank account updates

Amount thresholds: Auto-allow spend actions up to a defined dollar threshold, require approval in a middle band, and block above a maximum unless the caller is a finance-admin identity

Vendor allowlist / denylist: Allow spend actions only for approved vendors, and block known high-risk or disallowed merchant types

Category restrictions: Block or require approval for restricted spend categories unless the requester is in an approved role or cost center

Cost center / department scoping: Allow creates or edits only within the requester’s cost center, and block cross-department actions unless the caller has a finance role

Receipt enforcement: Prevent approvals or closeout steps when required receipts are missing, especially for transactions over a set amount

How can I start using Merge Agent Handler’s Ramp MCP server?

You can take the following steps:

1. Create an Agent Handler account and get your API key. Your MCP client will use this as a bearer token when calling the Agent Handler MCP endpoint.

2. Create a Tool Pack for your Ramp workflow. Tool Packs define which connectors and tools your agent can see and use.

3. Add the Ramp connector to that Tool Pack and select the specific Ramp tools you want exposed. Keep it narrow at first. For example, start read-only, then expand.

4. Create a Registered User (or decide on a service-account pattern). This is the identity boundary that holds credentials and scopes audit logs for tool calls.

5. Authenticate Ramp for that Registered User via Merge Link. Once authenticated, the Ramp tools will be callable under that identity.

6. Generate your MCP URL using the Tool Pack ID and Registered User ID. This is the MCP endpoint you’ll add to your MCP client.

7. Add the MCP server to your MCP client and include your API key in headers. Use <code class="blog_inline-code">Authorization: Bearer <YOUR_AGENT_HANDLER_API_KEY></code> (or the equivalent config for Cursor, Claude Desktop, VS Code, Windsurf, etc.).

8. Test a few simple Ramp tool calls, then verify in logs. Start with low-risk read calls, and confirm the tool calls look correct in Agent Handler’s observability/audit trail.

9. Before production, add security rules. Configure DLP and action-gating rules to block or redact sensitive data and to prevent risky Ramp actions (like bulk export or money movement) unless explicitly allowed.

Can employees use Merge Agent Handler to connect their AI tools to Ramp?

Yes, Agent Handler for Employees lets your employees connect Claude, ChatGPT, Microsoft Copilot, Cursor, and other MCP-compatible AI tools to Ramp without bypassing IT governance.

Instead of setting up direct connections with personal credentials that IT can't monitor or revoke, each employee authenticates through Agent Handler and gets individual credentials tied to their identity.

IT also provisions access by role or group via SCIM. A finance analyst, for example, gets Ramp access to review spend and card transactions, NetSuite to reconcile expenses against the general ledger, and Google Sheets to report on budget vs. actuals; while an HR manager gets Ramp access to monitor employee card limits, Workday to cross-reference employee records, and BambooHR to manage reimbursement policies.

Every tool call an employee's AI makes to Ramp is also inspected against your DLP rules and logged to a searchable audit trail, giving security teams full visibility into what data was accessed and by whom.