Guides

Troubleshooting

Fix auth drops, stale tools, scope errors, and common MCP limits.

Authentication fails or the connection drops

Reconnect per client:

  • Claude Code — run /mcp, select Ramp, and choose "Clear authentication".
  • Cursor — toggle Ramp in Cursor Settings -> MCP, or run agent mcp login ramp.
  • Claude — disconnect and reconnect Ramp in Settings -> Connectors.
  • ChatGPT — disconnect and reconnect the Ramp app in Settings -> Apps or reconnect the custom connector in Settings -> Connectors.
  • Perplexity — remove and re-add Ramp in connector settings.
  • Clear cached MCP auth if needed: rm -rf ~/.mcp-auth.
  • Make sure you're logged into the correct Ramp account.

CLI session keeps logging out

If you're inside the refresh window (read-write: 24 hours; read-only: one week) but still getting kicked out, your agent runtime is probably rewriting ~/.config/ramp/config.toml on restart. See Going to production.

New tools aren't showing up

The MCP tool surface grows continuously. Have the agent disconnect and reconnect (or run /mcp in Claude Code) to pick up additions.

Unsupported redirect URI

Custom MCP clients and gateways must have their exact redirect URI allowlisted before OAuth can complete. Submit a Developer API support ticket with your client name and the exact redirect URI.

"Query returned more than 100 rows"

MCP caps results at 100 rows per query. Ask for a narrower date range, vendor, cardholder, department, entity, or other filter.

"ETL operation limit reached"

Wait for current data operations to finish, or ask the agent to clear unused tables to free up resources. Persistent errors resolve within minutes.

Agent Cards scope errors

Agent Card endpoints require cards:read_agentic (and spend_limits:write for writes). Ask a Ramp admin to grant access. On the CLI, run ramp update first — older versions surface less-helpful scope errors.

Receipt uploads do not work through chat attachments

Ramp MCP connections do not currently receive receipt images or PDFs attached to the chat. Use the CLI, Ramp dashboard, or another supported upload path for receipt handling.

For anything else, submit a Developer API support ticket.