title: AI Agents source_url: /developer-api/v1/build-for-ai-agents summary: Give an AI agent read access, action authority, and (with approval) real purchasing power on Ramp — through MCP, the Ramp CLI, or both. Every action respects the authenticated user's role and lands in the Ramp audit log. content: Give an AI agent read access, action authority, and (with approval) real purchasing power on Ramp — through MCP, the Ramp CLI, or both. Every action respects the authenticated user's role and lands in the Ramp audit log. An agent that can do useful work on Ramp without copy-paste: Agents reach Ramp through two channels — MCP (the Model Context Protocol — the standard way assistants connect to external systems) or the Ramp CLI (a local runtime that brokers calls and ships skills). Pick one, run both side-by-side, or compose them. Both honor the authenticated user's permissions and write every action to the audit log. Estimated time: 5–15 minutes to your first agent action via MCP. Required for any agent integration: a Ramp production or sandbox account, and access to a supported client. Required for production MCP when you're embedding Ramp MCP in your own product or behind a custom client: redirect-URI whitelisting via Ramp support. Tech partners building a product that connects customers' Ramp accounts apply through Partner Integrations. Required for Agent Cards: at least one active fund. MCP Ramp CLI Best for Off-the-shelf assistants (Claude, ChatGPT, Cursor, Claude Code, etc.) and any MCP-compatible tool Coding agents (or any agent with terminal access) and scripted/scheduled workflows Setup One-click in supported clients; custom config for everything else curl ... | sh, then ramp auth login Surface Tool calls dispatched by the AI client Commands + skills invoked by the agent Auth Browser OAuth on first use Browser OAuth on first use; session reusable on remote hosts Best capability fit Conversational analysis, approvals, edits Scripted reads/writes, agent-driven purchases via the agentic-purchase skill The two channels expose overlapping capabilities — both can call Ramp MCP tools. The CLI adds skills (like agentic-purchase) that compose tool calls into a workflow. Most teams pick one and add the other when a specific capability requires it. External MCP client authorization External MCP clients are supported, but you must authorize through the shared Ramp MCP OAuth client, not through your own Developer API OAuth application. Pattern A: connect via MCP Ramp ships an MCP server at https://mcp.ramp.com/mcp (demo data: https://demo-mcp.ramp.com/mcp). The simplest integration is a supported client; a custom client works too once a redirect URI is allowlisted. One-click in the client's directory or a single command in a terminal client: Other MCP-compatible tools (Notion, Codex, Windsurf, Continue, etc.) connect with the same server URL. If you manage multiple Ramp businesses, add one MCP connection per business. See Ramp MCP for the full setup matrix and multi-business URL pattern. Embedding Ramp MCP in your own product, or routing through a gateway like Glean, MintMCP, or GoSearch? Ramp must allowlist the redirect URI first. Use https:// or localhost/127.0.0.1 only. Exact host required — wildcard subdomains aren't supported. Submit a Developer API support ticket with your client name and redirect URI. Tech partners apply through Partner Integrations. Microsoft Copilot for 365 Microsoft Copilot for 365 doesn't natively support remote MCP servers. Integrate via Copilot Studio's MCP server integration, or use the Developer API directly through Power Automate. Pattern B: connect via the Ramp CLI The CLI is the right channel when the agent has terminal access or runs as a script/scheduled job — coding agents (Claude Code, Cursor, Codex), CI workflows, headless services on a remote host. For remote hosts, authenticate locally and copy the session config — see Going to production below. Full command reference and skill catalog: Ramp CLI. The CLI exposes packaged skills an agent can invoke. The most common one for AI-driven flows: agentic-purchase — drives the Agent Cards capability end-to-end (request credential → checkout → audit). Install the skill URL into your agent: https://github.com/ramp-public/ramp-cli/blob/main/src/ramp_cli/skills/agentic-purchase/SKILL.md. Skills can call MCP tools under the hood, so an agent with CLI access also has the full MCP capability surface. CLI backing endpoints The CLI is built on top of the https://api.ramp.com/agent-tools endpoints. These endpoints are not accessible to external clients. What an AI agent can do on Ramp Capabilities are grouped here by what the agent does for the user, not by tool name. The underlying MCP tool surface evolves continuously — disconnect and reconnect your client to pick up new tools as they ship. For the channel-specific capability surface, see Ramp MCP → What you can do. Search transactions by merchant, amount, date, or user. Pull full spend exports and run SQL-style analysis (admins). Load vendor lists, accounting categories, tracking categories, departments, entities, treasury balances, and the org chart. Get explanations for declined transactions and policy guidance for borderline ones. Approve or reject transactions, reimbursements, and unified requests (purchase orders, fund requests, procurement approvals). View pending approvals across types. Bill approvals aren't yet available via MCP — use the Ramp UI or the Blank Canvas Approvals API for now. Edit transaction memos, fund assignment, accounting categories, and trip assignment. Submit and resubmit reimbursements. Post comments and mention users on workflow items. Lock, unlock, and activate cards. Connect transactions to trips. Apply GL coding to transactions and reimbursements. Policy Q&A from natural-language prompts ("Is this within policy?"). Help Center search. Decline explanations for transactions that didn't go through. The credential is merchant- and amount-scoped, requested immediately before one checkout, and not for subscriptions or later merchant charges; use Virtual Cards for those reusable cases. If you're building with Start here A user-session assistant or terminal agent Run the Agentic Purchase playbook. A company-owned standalone agent Follow the Agentic Payments guide. Standalone agents are in limited early access. Create trips, view trips with status filters, connect transactions to trips, retrieve flight and hotel bookings. Going to production Production MCP for custom clients and partner products is gated: Custom apps and third-party gateways — submit a support ticket to allowlist your redirect URI before launch. Tech partners building a product that connects customers' Ramp accounts — apply through the Partner Integrations launch checklist. Audit log — every write operation lands in the customer's Ramp audit log automatically, no extra wiring. Customers control which employees can use Ramp MCP through their dashboard: Company → Integrations → Ramp MCP → Manage Access. Restrict by role, department, or specific users. The MCP server respects each user's existing Ramp permissions on top of that — employees see only their own data; admins see company-wide data. Read-only sessions expire one week after last use. Read-write sessions expire 24 hours after last use. For remote hosts, authenticate locally and copy the session config: As long as the agent makes at least one call within the refresh window, the session doesn't expire. Some hosted runtimes rewrite ~/.config/ramp/config.toml on restart, which removes the refresh token. Persist the file outside the rewrite scope or restore it at startup. Treat config.toml like a credential and never commit it to source control. New MCP tools ship continuously. Have agents disconnect and reconnect (or run /mcp in Claude Code) to pick up additions. The capability surface in this Use case is grouped by user job — specific tool names will drift; the categories shouldn't. Query result cap: 100 rows per MCP query. Clients auto-add filters and retry on overflow. ETL data tables: "too many tables loaded" errors clear by asking the agent to drop unused tables; persistent errors resolve within minutes. Spend programs — back agent purchases with recurring-budget templates instead of one-off funds. Make purchases with Agent Cards — give an agent a purchase-scoped credential for one approved checkout. Virtual cards — deliver reusable card details to a person or conventional backend through an embedded iframe or the Vault API. Cards — choose between physical cards, reusable virtual cards, and purchase-scoped Agent Cards. Spend Controls — the funds, spend programs, and approvals that constrain agent spend. Reimbursements — agents can submit and approve reimbursements via MCP. Procurement — agents can approve unified requests (POs, fund requests). Ramp MCP — the protocol surface and supported-client setup matrix. Ramp CLI — the runtime, command reference, and skill catalog. Funds — funds that constrain what an agent can spend. Spend Programs — recurring-budget templates for agent purchases. FAQ The https://api.ramp.com/agent-tools endpoints that back the CLI are not accessible to external clients. To connect to Ramp MCP from a third-party client, see the external MCP client authorization guidance above. Yes. They're independent channels using the same OAuth-authenticated session. Pick MCP for conversational/UI-driven flows, the CLI for terminal/scripted ones. Bill approvals route through Ramp's Blank Canvas Approvals system. For now, approve bills in the Ramp UI or via Blank Canvas Approvals. MCP coverage is on the roadmap. No. Most of the capability surface (reads, approvals, edits, policy Q&A) works without Agent Cards. Agent Cards only matters when the agent needs real payment authority. Use the ramp feedback command in the CLI, the in-client feedback in your MCP client, or submit a support ticket. New tools ship continuously.