How to connect Ramp MCP with Claude Code (4 steps)

Developers building reconciliation tools, spend dashboards, or policy alerts currently have to hit Ramp's API directly: setting up an OAuth client, requesting scopes, and writing a one-off integration for each new report.

To help your developers query transactions, reimbursements, and spend data from Ramp without leaving the terminal, we'll show you how to connect Ramp with Merge Agent Handler's Ramp MCP server.

How it works

Merge Agent Handler sits between Claude Code and Ramp's API.

You install the Merge CLI, authenticate once with your Merge Agent Handler account, and register the connection with a single command.

Merge will manage Ramp's OAuth client credentials and token refresh on your behalf, so you never store a client secret locally or handle token rotation yourself.

Related: How to use a Ramp MCP in Codex

Prerequisites

Before getting started, you'll need the following:

• A Merge Agent Handler account
• Claude Code installed (run claude --version to confirm)
• pipx installed (run pipx --version to confirm, or install via pip install pipx)
• A Ramp account with admin access to authorize an API client

If you want to connect Merge Agent Handler's Ramp MCP with internal or customer-facing agentic products, you can follow the steps in our docs.

1. Install the Merge CLI

Install with pipx: pipx install merge-api

Then confirm the installation: merge --version

2. Log in to Merge

Run merge login to authenticate the CLI with your Merge Agent Handler account: merge login

This authenticates your session so the CLI can make authorized requests on your behalf going forward.

3. Add Agent Handler to Claude Code

The simplest way to register Agent Handler with Claude Code:

merge setup claude-code

4. Authenticate Ramp

Open a Claude Code session and try: "List all card transactions from the last 7 days that don't have a receipt attached, grouped by cardholder."

The first time you invoke a Ramp tool, a Magic Link will appear to complete connector authentication.

{{this-blog-only-cta}}

Ramp MCP FAQ

In case you have more questions on setting up and using the Ramp MCP in Claude Code, we've addressed several more commonly-asked questions below.

What can you do once the Ramp MCP is connected to Claude Code?

With Ramp connected, Claude Code can:

• Query card transactions: retrieve transactions filtered by cardholder, department, merchant, or date range, including memo and receipt status

• List reimbursements: pull out-of-pocket expense submissions and their approval status without opening the Ramp dashboard

• Check card and spend limits: retrieve active cards, their spending limits, and remaining balance for a given cardholder or department

• Read accounting sync data: query GL code and accounting category assignments on transactions before they sync to the general ledger

• Manage bill pay: retrieve vendor bills and their payment or approval status

• Create or update transactions: attach receipts or update GL coding directly from the terminal, if write tools are enabled in your Tool Pack

Why use Merge Agent Handler vs. building directly on the Ramp API?

You can build directly against Ramp's API. For a developer with a single, narrow use case, that's workable: register an OAuth client, request the scopes you need, and start making requests.

The friction shows up at team scale.

Ramp's OAuth scopes are too coarse: read access to transactions also exposes bill pay and employee data, so a reconciliation agent can't get read-only transaction access alone. Agents also share one client credential, meaning no per-agent audit trail and risky, manual secret rotation.

Merge Agent Handler manages Ramp's OAuth credentials centrally and adds a control layer on top.

You can scope which Ramp operations a given agent is allowed to call, so a tool built for expense reporting doesn't also get access to bill pay or spend-limit changes. Every tool call is logged with the timestamp, tool name, and inputs, which matters when the data involves real company spend.

For a solo developer prototyping against a sandbox, a direct API client is fine. For a finance or engineering team running agents against production spend data, the access scoping and audit trail are what make the deployment defensible.

Why connect Ramp to Claude Code?

Ramp holds the operational record of company spend: card transactions, reimbursements, vendor bills, and the accounting codes everything eventually syncs against.

Teams that need to build on that data, whether for reconciliation, policy enforcement, or reporting, currently have to pull it out through exports or a dedicated integration.

With the Ramp MCP connected, Claude Code can query that data directly and act on it inside the same session. You can ask it to flag transactions missing receipts before a close deadline, summarize reimbursements pending approval by department, or check whether a vendor bill is on track to be paid before it's due.

Can I use Merge's Ramp MCP with my employees?

Yes, Merge for Workforce is built to help organizations provision, secure, and govern how employees connect AI to systems like Ramp.

Common patterns include:

• Provisioning and access control via SCIM with identity providers like Okta and Microsoft Entra ID, so IT can manage which employees can query transaction and spend data by role or team

• DLP and policy enforcement on tool calls, so admins can block queries that would return card numbers or other cardholders' spend data before results reach the employee's AI session

• User-level audit logging so security and finance teams can review which transactions, reimbursements, or bills were queried or modified, by which employee identity, and when

Put together, employees can use the Ramp MCP to review spend, audit missing receipts, check reimbursement status while building internal tools, and more, while IT keeps centralized control over which spend data each agent can reach.