Agentic Data Plane

Ramp Managed MCP Server

The Ramp managed MCP server lets an LLM read and act on your company’s Ramp spend data. With it, an LLM can list and inspect transactions, browse cards, manage spend limits, query users and departments, look up vendors, and review reimbursements.

After reading this page, you will be able to:

  • Configure the Ramp managed MCP server with per-user OAuth

  • Pick the right scopes and environment for production vs sandbox

  • List transactions, manage cards, and adjust spend limits from an agent

What this MCP server does

Wraps the Ramp Developer API v1 using per-user OAuth tokens, so each user’s Ramp permissions are enforced automatically and no shared API key is stored. Ramp lets only users with permission to authorize Developer API applications, typically Admin and Business Owner users, complete the consent flow. Other users see a "Business not authorized to use this application" error.

It is suitable for expense analysis, spend-policy enforcement, and corporate card management workflows. It is not intended for accounting system integrations or bulk data exports. Use Ramp’s native accounting sync or data export features for those tasks.

Prerequisites

Before you create the server, make sure you have:

  • A Ramp account where you can create a Developer API application, and Ramp users with permission to authorize Developer API applications. Ramp typically limits that permission to Admin and Business Owner users.

  • An OAuth provider configured in Redpanda Agentic Data Plane for Ramp. See Configure an OAuth Provider.

  • Familiarity with User-delegated OAuth.

Get Ramp credentials

Set up the OAuth app on Ramp and the matching OAuth provider in Agentic Data Plane. Ramp keeps production and sandbox separate, so register the app in the environment the MCP server targets, and use that environment’s endpoints. Tokens issued in one environment don’t work in the other.

  1. In Ramp, create a Developer API application. See Ramp’s authorization guide.

  2. Set the redirect URI to your AI Gateway OAuth callback (typically https://aigw.<cluster-id>.clusters.rdpa.co/oauth/v1/callback).

  3. Note the Client ID and Client Secret.

  4. Grant the application these scopes:

    • transactions:read

    • cards:read

    • cards:write

    • users:read

    • departments:read

    • vendors:read

    • reimbursements:read

    • limits:read

    • limits:write

  5. In Agentic Data Plane, create a custom OAuth provider with:

    • Authorization endpoint: https://app.ramp.com/v1/authorize for production, or https://demo.ramp.com/v1/authorize for the sandbox

    • Token endpoint: https://api.ramp.com/developer/v1/token for production, or https://demo-api.ramp.com/developer/v1/token for the sandbox

    • Scopes: The same scopes you granted the Ramp application

    • Token endpoint authentication method: Client Secret (Basic), because Ramp expects the client ID and secret in a Basic Authorization header

    • The Client ID and a secret-store reference for the Client Secret

Configure

Create a new Ramp MCP server in Agentic Data Plane:

  1. Open MCP servers in the sidebar.

  2. Click Add MCP server.

  3. Click the Ramp card in the marketplace picker.

  4. Replace the suggested Name, and optionally add a Description.

  5. In the Ramp configuration form:

    Field Notes

    environment

    production for the live Ramp API. demo for Ramp’s sandbox environment. Omit (or leave empty) for production. The OAuth provider must use the same environment’s endpoints.

    OAuth Provider

    The Ramp OAuth provider you configured.

    Required scopes

    All the scopes from Get Ramp credentials. Drop write scopes (cards:write, limits:write) if the MCP only needs to read. Every required scope must also be in the provider’s scopes. A required scope the provider doesn’t request makes tool calls fail with scope_upgrade_required until each user reconnects and grants it. If the Ramp application isn’t allowed to grant that scope, every tool call keeps failing.

    Enabled under Queryable

    Appears only if SQL tools are available in your organization, and starts on. Turn it off unless your agents need the two SQL tools. See Expose Ramp data as SQL tables.

  6. Click Create server.

Configure from the CLI

Ramp authenticates per-user through the Ramp OAuth provider you configured. Reference that provider in the managed configuration’s userOauth.providerName field. Ramp supports per-user OAuth only, so the userOauth block is required. The --remote.user-oauth.provider-name and --remote.user-oauth.required-scopes flags belong to the remote flag group, so they apply to remote servers only.

rpk ai mcp-server create my-ramp --enabled --managed.config '{
  "@type": "type.googleapis.com/redpanda.mcps.ramp.v1.RampMCPConfig",
  "environment": "production",
  "userOauth": {
    "providerName": "ramp"
  }
}'

Set environment to "demo" to target Ramp’s sandbox, with an OAuth provider that uses the sandbox endpoints. userOauth.providerName is the resource name of the Ramp OAuth provider you registered.

The create form turns Enable code mode on by default for this server type. rpk ai mcp-server create has no code-mode flag. To add code mode from the CLI, create a Code MCP server named <server-name>-code with --code.mcp-servers <server-name>. See Code Mode.

Tools

The Ramp MCP exposes these tools:

Tool Description

list_transactions

List transactions with optional filters. Supports pagination through the start cursor. Returns up to page_size results (max 100).

get_transaction

Retrieve a single transaction by ID, including line items, accounting selections, and policy violations.

list_cards

List corporate cards. Supports pagination.

create_card

Issue a new virtual card. Returns a deferred task ID, since Ramp creates cards asynchronously.

suspend_card

Suspend an active card by ID. Returns a deferred task ID.

list_users

List Ramp users in your organization. Supports pagination.

list_departments

List departments. Supports pagination.

list_vendors

List vendors. Supports pagination.

list_reimbursements

List out-of-pocket reimbursement requests. Supports pagination.

list_limits

List spend limits. Supports pagination.

create_limit

Create a new spend limit. Returns a deferred task ID, since Ramp creates limits asynchronously.

update_limit

Update an existing spend limit’s display name or spending restrictions synchronously.
list_cards, create_card, suspend_card, list_limits, create_limit, and update_limit call Ramp card and spend-limit endpoints that aren’t in Ramp’s current Developer API reference. If one of these tools returns a not-found error, do that task in the Ramp web app instead. The transaction, user, department, vendor, and reimbursement tools use documented endpoints.

Example: List recent transactions

curl -s https://aigw.<cluster-id>.clusters.rdpa.co/mcp/v1/my-ramp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_transactions",
      "arguments": {
        "page_size": 25
      }
    }
  }'

Example: Create a virtual card for a vendor

curl -s https://aigw.<cluster-id>.clusters.rdpa.co/mcp/v1/my-ramp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "create_card",
      "arguments": {
        "display_name": "AWS Services",
        "user_id": "usr_abc123",
        "idempotency_key": "create-aws-card-2026",
        "spending_limit_amount": 5000.0,
        "spending_limit_interval": "MONTHLY",
        "spending_limit_currency": "USD"
      }
    }
  }'

Expose Ramp data as SQL tables

The Ramp server can also present its list operations as read-only SQL tables, so an agent can filter spend data the way it would query a database. SQL exposure is the Enabled toggle under Queryable in the server’s configuration. If SQL tools are available in your organization, the create form shows Queryable with Enabled on, so a server you create there is queryable unless you turn it off. Otherwise the form doesn’t show Queryable, and the server starts with SQL exposure off. Creating a server with rpk ai leaves SQL exposure off unless the managed configuration sets it. An existing server keeps the setting it was saved with. To change it, open the server’s edit form, which shows Queryable if SQL tools are available in your organization or if the server was saved with SQL exposure on. SQL exposure adds two tools:

  • list_tables: Return the table catalog. For each table, the catalog lists its columns and their types, which columns can be filtered and with which operators, whether each filter is exact, the page-size limit, and a schema fingerprint that every query response repeats so a caller can tell when the catalog changed.

  • execute_query: Run one query against a table and return a page of rows plus a cursor for the next page.

The tables are:

Table Contents

transactions

The card transactions the connected user can see, in every state except declined. Ramp leaves declined transactions out unless a request asks for them, and the server doesn’t. You can filter on sync_status.

users

The business’s active and inactive users. Ramp leaves suspended users out unless a request asks for them, and the server doesn’t. You can filter on department_id and location_id.

departments

Every department of the business. The table offers no filters.

vendors

The business’s published vendors, active and inactive. Draft vendors and vendors waiting for creation approval aren’t listed. You can filter on is_active.

reimbursements

The reimbursements the connected user can see, paid from the business to a user. Employee repayments to the business aren’t listed, because Ramp returns them only when a request asks for that direction. You can filter on user_id and state.

No filter on these tables is exact. The catalog marks each one inexact, so re-apply the filter to the rows you read back. A page holds at most 100 rows on every table.

The tools that read a single transaction, or that read or change cards and spend limits, stay plain tools.

With SQL exposure on, the two tools are available to every caller of the server, including agents. Turn off Enabled on a server whose agents should only reach the curated Ramp tools.

To trim the catalog table by table, hide columns, require filters, retype a column, or serve a table under another name, use the SQL exposure tab on the server’s page. That tab works the same way for every managed type that offers SQL tables. See Narrow what the SQL tools expose. If the server’s page has no SQL exposure tab, narrowing isn’t enabled for your organization. The Enabled setting on the server’s configuration still turns the two SQL tools on and off.

Troubleshooting

Common symptoms and fixes:

Symptom What to check

connection_required

First call from a user with no stored token. The failed tool result carries the authorization URL. The user completes Ramp’s OAuth consent flow, the token lands in the vault, and subsequent calls reuse it.

scope_upgrade_required

The server’s required_scopes was extended after users had already consented, so users reconnect to grant them. If it persists after reconnecting, a required scope is missing from the provider’s scopes or from the Ramp application.

Business not authorized to use this application during consent

The user’s Ramp role can’t authorize Developer API applications. Ask a Ramp Admin or Business Owner to complete the consent flow instead.

Tokens fail with an authorization error right after consent

Confirm the OAuth provider’s endpoints and the server’s environment point at the same Ramp environment. Production tokens don’t work against the sandbox, and sandbox tokens don’t work against production.

create_card / create_limit returns a task ID with no card / limit details

These operations are asynchronous on Ramp’s side. The MCP returns the task ID, but no MCP tool checks the task’s status. The card or limit appears after the task completes. Check for it in the Ramp web app.

403 Forbidden reading or writing

The calling user’s Ramp role doesn’t grant the action. Ramp’s role-based access control runs end-to-end. Per-user OAuth means each user only sees what their Ramp account permits.

Limitations

This page does not cover:

  • Bulk data export: Use Ramp’s native data export.

  • Accounting system integration: Use Ramp’s accounting sync.

  • Receipt management and approvals: Handled in the Ramp web UI.

Next steps