Guides

Connecting

There are three ways to connect your agents to Ramp:

MCP, CLI, and API connection options
CriterionCLIRecommendedMCP ConnectorsAPI
Set up
Instant
Instant to 15 minutes
Hours to days
How it runs

In a terminal, local agent, script, or CI

Inside a conversational assistant

In deterministic code

Permission and Attribution

Actions are attributed to the acting user or agent. The agent acts as the Ramp user who authenticated the connection. Permissions do not exceed the user or agent's role.

Actions are attributed to the acting user or agent. The agent acts as the Ramp user who authenticated the connection. Permissions do not exceed the user or agent's role.

Actions are scoped to the business owner's identity.

Strengths

Structured output, broad workflows, and easy local automation

Easy setup, already available in some cases, and instant with Claude chat or an out-of-the-box connector

Maximum control over interfaces, workflows, and backend logic

Weaknesses

Requires installation and access to a coding agent or terminal

File uploads and downloads not available, slower performance

Requires the most engineering, security, and lifecycle ownership

Use the Ramp app when a person needs to review context, handle an exception, or complete work directly.

The full list of tools available in the CLI and MCP can be found here.

CLI

Use the CLI when the agent has terminal access, needs structured output, or should follow a repeatable skill. The CLI works well in Claude Code, Codex, Cursor, scripts, and CI.

Connect via MCP

Choose the client you already use. Each link opens the fastest available way to add Ramp.

ClaudeConnect Ramp in Claude and authorize the Ramp account you want the assistant to use.ChatGPTAdd the Ramp app in ChatGPT and complete browser authorization.CursorInstall Ramp MCP in Cursor with one click, then authorize your Ramp account.PerplexityAdd Ramp from Perplexity's connector settings and complete browser authorization.Custom MCPConnect another MCP client using Ramp's hosted endpoint and browser authorization.

Custom MCP clients

Use this path when your client does not have a ready-made Ramp connector.

Connect a live Ramp business to:

https://mcp.ramp.com/mcp

Use sample data instead at:

https://demo-mcp.ramp.com/mcp

Clients that read MCP JSON usually expect:

{
  "mcpServers": {
    "ramp": {
      "url": "https://mcp.ramp.com/mcp"
    }
  }
}

The connection acts as the Ramp user who completes browser authorization. What the client can see and change follows that user's Ramp permissions.

Custom clients and gateways must have their exact redirect URI allowlisted before Ramp authorization can complete:

  • Use https://, localhost, or 127.0.0.1.
  • Submit the exact host. Wildcard subdomains are not supported.
  • Request redirect URI access for the client or gateway.

Developer API

Use the API when your product owns the interface and backend workflow. Your team is responsible for OAuth, scopes, webhooks, retries, and the customer experience.

View API reference

Troubleshooting

Authentication drops or tools look stale

Reconnect Ramp in the client so OAuth and the cached tool list refresh:

  • Claude: disconnect and reconnect Ramp in Settings → Connectors.
  • Cursor: toggle Ramp in Cursor Settings → MCP.
  • ChatGPT: disconnect and reconnect Ramp in Settings → Apps or the connector settings.
  • Perplexity: remove Ramp and add it again in connector settings.

If a custom client keeps stale credentials, clear its cached MCP auth. Confirm that the browser completed authorization against the intended Ramp business.

The CLI keeps logging out

Read-write CLI sessions normally refresh for 24 hours, while read-only sessions can refresh for one week. If the CLI logs out sooner, confirm that the runtime preserves ~/.config/ramp/config.toml. Ephemeral coding environments may replace that file between sessions.

A query returns too much data

MCP caps a query response at 100 rows. Narrow the date range, vendor, cardholder, department, entity, or another available filter.

ETL operation limit reached

Wait for current data operations to finish, or clear unused tables before trying again. Persistent capacity errors usually resolve within minutes.

Unsupported redirect URI

Custom clients and gateways need their exact redirect URI allowlisted. Use the Custom MCP clients instructions to submit the URI.

A receipt attachment does not reach MCP

Use the Ramp CLI, Ramp dashboard, or another supported upload path for receipt images and PDFs. Chat attachments are not automatically forwarded to Ramp MCP.