How to integrate Ramp MCP with LlamaIndex

This guide walks you through connecting Ramp to LlamaIndex using the Composio tool router. By the end, you'll have a working Ramp agent that can download last month's statement as pdf, list all transactions over $500 this week, get details of your virtual cards through natural language commands. This guide will help you understand how to give your LlamaIndex agent real control over a Ramp account through Composio's Ramp MCP server. Before we dive in, let's take a quick look at the key ideas and tools involved.

Ramp logoRamp
Oauth2

Ramp is a finance automation platform for tracking business expenses and income. It helps you manage spending and gain actionable insights into your company's finances.

88 Tools

Introduction

This guide walks you through connecting Ramp to LlamaIndex using the Composio tool router. By the end, you'll have a working Ramp agent that can download last month's statement as pdf, list all transactions over $500 this week, get details of your virtual cards through natural language commands.

This guide will help you understand how to give your LlamaIndex agent real control over a Ramp account through Composio's Ramp MCP server.

Before we dive in, let's take a quick look at the key ideas and tools involved.

Also integrate Ramp with

TL;DR

Here's what you'll learn:
  • Set your OpenAI and Composio API keys
  • Install LlamaIndex and Composio packages
  • Create a Composio Tool Router session for Ramp
  • Connect LlamaIndex to the Ramp MCP server
  • Build a Ramp-powered agent using LlamaIndex
  • Interact with Ramp through natural language

What is LlamaIndex?

LlamaIndex is a data framework for building LLM applications. It provides tools for connecting LLMs to external data sources and services through agents and tools.

Key features include:

  • ReAct Agent: Reasoning and acting pattern for tool-using agents
  • MCP Tools: Native support for Model Context Protocol
  • Context Management: Maintain conversation context across interactions
  • Async Support: Built for async/await patterns

What is the Ramp MCP server, and what's possible with it?

The Ramp MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your Ramp account. It provides structured and secure access to your company's financial data, so your agent can fetch transactions, analyze card activity, generate statements, manage departments, and retrieve detailed expense information on your behalf.

  • Comprehensive transaction tracking: Instantly pull lists of all your business transactions or your own card activity, making it easy to monitor expenses and spot anomalies.
  • Card management and insights: Retrieve details about specific Ramp cards or see all cards assigned to you, including limits, status, and cardholder info for better financial oversight.
  • Automated statement generation: Ask your agent to generate and download account statements in multiple formats (PDF, CSV, JSON) for reporting or bookkeeping.
  • Department and organizational management: Create new departments or fetch detailed department profiles to help structure your expense tracking and categorize spending.
  • Detailed transaction analysis: Dive into specific transactions to get merchant information, receipts, dispute details, and accounting codes for audit and compliance purposes.

What is the Composio tool router, and how does it fit here?

What is Composio SDK?

Composio's Composio SDK helps agents find the right tools for a task at runtime. You can plug in multiple toolkits (like Gmail, HubSpot, and GitHub), and the agent will identify the relevant app and action to complete multi-step workflows. This can reduce token usage and improve the reliability of tool calls. Read more here: Getting started with Composio SDK

The tool router generates a secure MCP URL that your agents can access to perform actions.

How the Composio SDK works

The Composio SDK follows a three-phase workflow:

  1. Discovery: Searches for tools matching your task and returns relevant toolkits with their details.
  2. Authentication: Checks for active connections. If missing, creates an auth config and returns a connection URL via Auth Link.
  3. Execution: Executes the action using the authenticated connection.

Step-by-step Guide

Step by step10 STEPS
1

Prerequisites

Before you begin, make sure you have:
  • Python 3.8/Node 16 or higher installed
  • A Composio account with the API key
  • An OpenAI API key
  • A Ramp account and project
  • Basic familiarity with async Python/Typescript
2

Getting API Keys for OpenAI, Composio, and Ramp

OpenAI API key (OPENAI_API_KEY)
  • Go to the OpenAI dashboard
  • Create an API key if you don't have one
  • Assign it to OPENAI_API_KEY in .env
Composio API key and user ID
  • Log into the Composio dashboard
  • Copy your API key from Settings
    • Use this as COMPOSIO_API_KEY
  • Pick a stable user identifier (email or ID)
    • Use this as COMPOSIO_USER_ID
3

Installing dependencies

npm install @composio/llamaindex @llamaindex/openai @llamaindex/tools @llamaindex/workflow dotenv

Create a new Typescript project and install the necessary dependencies:

  • @composio/llamaindex: Composio's LlamaIndex integration
  • @llamaindex/openai: OpenAI LLM integration
  • @llamaindex/tools: MCP client for LlamaIndex
  • @llamaindex/workflow: Workflow framework for LlamaIndex
  • dotenv: Environment variable management
4

Set environment variables

bash
OPENAI_API_KEY=your-openai-api-key
COMPOSIO_API_KEY=your-composio-api-key
COMPOSIO_USER_ID=your-user-id

Create a .env file in your project root:

These credentials will be used to:

  • Authenticate with OpenAI's GPT-5 model
  • Connect to Composio's Tool Router
  • Identify your Composio user session for Ramp access
5

Import modules

import "dotenv/config";
import readline from "node:readline/promises";
import { stdin as input, stdout as output } from "node:process";

import { Composio } from "@composio/core";

import { mcp } from "@llamaindex/tools";
import { agent as createAgent } from "@llamaindex/workflow";
import { openai } from "@llamaindex/openai";

dotenv.config();

Create a new file called ramp_llamaindex_agent.ts and import the required modules:

Key imports:

  • dotenv.config loads .env at runtime
  • readline gives us a simple CLI chat loop
  • Composio is the main Composio SDK client
  • mcp connects to an MCP endpoint
  • createAgent builds a LlamaIndex agent
  • openai configures the LLM backend
6

Load environment variables and initialize Composio

const OPENAI_API_KEY = process.env.OPENAI_API_KEY;
const COMPOSIO_API_KEY = process.env.COMPOSIO_API_KEY;
const COMPOSIO_USER_ID = process.env.COMPOSIO_USER_ID;

if (!OPENAI_API_KEY) throw new Error("OPENAI_API_KEY is not set");
if (!COMPOSIO_API_KEY) throw new Error("COMPOSIO_API_KEY is not set");
if (!COMPOSIO_USER_ID) throw new Error("COMPOSIO_USER_ID is not set");

What's happening:

This ensures missing credentials cause early, clear errors before the agent attempts to initialise.

7

Create a Tool Router session and build the agent function

async function buildAgent() {

  console.log(`Initializing Composio client...${COMPOSIO_USER_ID!}...`);
  console.log(`COMPOSIO_USER_ID: ${COMPOSIO_USER_ID!}...`);

  const composio = new Composio({
    apiKey: COMPOSIO_API_KEY,
    provider: new LlamaindexProvider(),
  });

  const session = await composio.create(
    COMPOSIO_USER_ID!,
    {
      toolkits: ["ramp"],
    },
  );

  const mcpUrl = session.mcp.url;
  console.log(`Composio Tool Router MCP URL: ${mcpUrl}`);

  const server = mcp({
    url: mcpUrl,
    clientName: "composio_tool_router_with_llamaindex",
    requestInit: {
      headers: {
        "x-api-key": COMPOSIO_API_KEY!,
      },
    },
    // verbose: true,
  });

  const tools = await server.tools();

  const llm = openai({ apiKey: OPENAI_API_KEY, model: "gpt-5" });

  const agent = createAgent({
    name: "composio_tool_router_with_llamaindex",
        description : "An agent that uses Composio Tool Router MCP tools to perform actions.",
    systemPrompt:
      "You are a helpful assistant connected to Composio Tool Router."+
"Use the available tools to answer user queries and perform Ramp actions." ,
    llm,
    tools,
  });

  return agent;
}

What's happening here:

  • We create a Composio client using your API key and configure it with the LlamaIndex provider
  • We then create a tool router MCP session for your user, specifying the toolkits we want to use (in this case, ramp)
  • The session returns an MCP HTTP endpoint URL that acts as a gateway to all your configured tools
  • LlamaIndex will connect to this endpoint to dynamically discover and use the available Ramp tools.
  • The MCP tools are mapped to LlamaIndex-compatible tools and plug them into the Agent.
8

Create an interactive chat loop

async function chatLoop(agent: ReturnType<typeof createAgent>) {
  const rl = readline.createInterface({ input, output });

  console.log("Type 'quit' or 'exit' to stop.");

  while (true) {
    let userInput: string;

    try {
      userInput = (await rl.question("\nYou: ")).trim();
    } catch {
      console.log("\nAgent: Bye!");
      break;
    }

    if (!userInput) {
      continue;
    }

    const lower = userInput.toLowerCase();
    if (lower === "quit" || lower === "exit") {
      console.log("Agent: Bye!");
      break;
    }

    try {
      process.stdout.write("Agent: ");

      const stream = agent.runStream(userInput);
      let finalResult: any = null;

      for await (const event of stream) {
        // The event.data contains the streamed content
        const data: any = event.data;

        // Check for streaming delta content
        if (data?.delta) {
          process.stdout.write(data.delta);
        }

        // Store final result for fallback
        if (data?.result || data?.message) {
          finalResult = data;
        }
      }

      // If no streaming happened, show the final result
      if (finalResult) {
        const answer =
          finalResult.result ??
          finalResult.message?.content ??
          finalResult.message ??
          "";
        if (answer && typeof answer === "string" && !answer.includes("[object")) {
          process.stdout.write(answer);
        }
      }

      console.log(); // New line after streaming completes
    } catch (err: any) {
      console.error("\nAgent error:", err?.message ?? err);
    }
  }

  rl.close();
}

What's happening:

  • We're creating a direct terminal interface to chat with Ramp
  • The LLM's responses are streamed to the CLI for faster interaction.
  • The agent uses context to maintain conversation history
  • The agent processes the request, selects appropriate Ramp tools, and returns a result
  • We extract the answer from the result data structure and display it to the user
  • You can type 'quit' or 'exit' to stop the chat loop gracefully
  • Agent responses and any errors are streamed in a clear, readable format
9

Define the main entry point

async function main() {
  try {
    const agent = await buildAgent();
    await chatLoop(agent);
  } catch (err) {
    console.error("Failed to start agent:", err);
    process.exit(1);
  }
}

main();

What's happening here:

  • We're orchestrating the entire application flow
  • The agent gets built with proper error handling
  • Then we kick off the interactive chat loop so you can start talking to Ramp
10

Run the agent

npx ts-node llamaindex-agent.ts

When prompted, authenticate and authorise your agent with Ramp, then start asking questions.

Complete Code

Here's the complete code to get you started with Ramp and LlamaIndex:

import "dotenv/config";
import readline from "node:readline/promises";
import { stdin as input, stdout as output } from "node:process";

import { Composio } from "@composio/core";
import { LlamaindexProvider } from "@composio/llamaindex";

import { mcp } from "@llamaindex/tools";
import { agent as createAgent } from "@llamaindex/workflow";
import { openai } from "@llamaindex/openai";

dotenv.config();

const OPENAI_API_KEY = process.env.OPENAI_API_KEY;
const COMPOSIO_API_KEY = process.env.COMPOSIO_API_KEY;
const COMPOSIO_USER_ID = process.env.COMPOSIO_USER_ID;

if (!OPENAI_API_KEY) {
    throw new Error("OPENAI_API_KEY is not set in the environment");
  }
if (!COMPOSIO_API_KEY) {
    throw new Error("COMPOSIO_API_KEY is not set in the environment");
  }
if (!COMPOSIO_USER_ID) {
    throw new Error("COMPOSIO_USER_ID is not set in the environment");
  }

async function buildAgent() {

  console.log(`Initializing Composio client...${COMPOSIO_USER_ID!}...`);
  console.log(`COMPOSIO_USER_ID: ${COMPOSIO_USER_ID!}...`);

  const composio = new Composio({
    apiKey: COMPOSIO_API_KEY,
    provider: new LlamaindexProvider(),
  });

  const session = await composio.create(
    COMPOSIO_USER_ID!,
    {
      toolkits: ["ramp"],
    },
  );

  const mcpUrl = session.mcp.url;
  console.log(`Composio Tool Router MCP URL: ${mcpUrl}`);

  const server = mcp({
    url: mcpUrl,
    clientName: "composio_tool_router_with_llamaindex",
    requestInit: {
      headers: {
        "x-api-key": COMPOSIO_API_KEY!,
      },
    },
    // verbose: true,
  });

  const tools = await server.tools();

  const llm = openai({ apiKey: OPENAI_API_KEY, model: "gpt-5" });

  const agent = createAgent({
    name: "composio_tool_router_with_llamaindex",
    description:
      "An agent that uses Composio Tool Router MCP tools to perform actions.",
    systemPrompt:
      "You are a helpful assistant connected to Composio Tool Router."+
"Use the available tools to answer user queries and perform Ramp actions." ,
    llm,
    tools,
  });

  return agent;
}

async function chatLoop(agent: ReturnType<typeof createAgent>) {
  const rl = readline.createInterface({ input, output });

  console.log("Type 'quit' or 'exit' to stop.");

  while (true) {
    let userInput: string;

    try {
      userInput = (await rl.question("\nYou: ")).trim();
    } catch {
      console.log("\nAgent: Bye!");
      break;
    }

    if (!userInput) {
      continue;
    }

    const lower = userInput.toLowerCase();
    if (lower === "quit" || lower === "exit") {
      console.log("Agent: Bye!");
      break;
    }

    try {
      process.stdout.write("Agent: ");

      const stream = agent.runStream(userInput);
      let finalResult: any = null;

      for await (const event of stream) {
        // The event.data contains the streamed content
        const data: any = event.data;

        // Check for streaming delta content
        if (data?.delta) {
          process.stdout.write(data.delta);
        }

        // Store final result for fallback
        if (data?.result || data?.message) {
          finalResult = data;
        }
      }

      // If no streaming happened, show the final result
      if (finalResult) {
        const answer =
          finalResult.result ??
          finalResult.message?.content ??
          finalResult.message ??
          "";
        if (answer && typeof answer === "string" && !answer.includes("[object")) {
          process.stdout.write(answer);
        }
      }

      console.log(); // New line after streaming completes
    } catch (err: any) {
      console.error("\nAgent error:", err?.message ?? err);
    }
  }

  rl.close();
}

async function main() {
  try {
    const agent = await buildAgent();
    await chatLoop(agent);
  } catch (err: any) {
    console.error("Failed to start agent:", err?.message ?? err);
    process.exit(1);
  }
}

main();

Conclusion

You've successfully connected Ramp to LlamaIndex through Composio's Tool Router MCP layer. Key takeaways:
  • Tool Router dynamically exposes Ramp tools through an MCP endpoint
  • LlamaIndex's ReActAgent handles reasoning and orchestration; Composio handles integrations
  • The agent becomes more capable without increasing prompt size
  • Async Python provides clean, efficient execution of agent workflows
You can easily extend this to other toolkits like Gmail, Notion, Stripe, GitHub, and more by adding them to the toolkits parameter.
TOOLS

Supported Tools

Every Ramp action and event your agent gets out of the box.

Create Department

Tool for creating a new department in your Ramp organization.

Create Inventory Item Accounting Field

Tool to create a new inventory item accounting field for tracking inventory categories.

Create Transaction Memo

Tool for uploading a new memo for a transaction in Ramp.

Create Mileage Reimbursement

Tool to create a mileage reimbursement in Ramp.

Create New Custom Accounting Field

Tool for creating a new custom accounting field.

Create Tax Code Accounting Field

Tool to create a new tax code accounting field in Ramp.

Create User Invite

Tool to create a user invite for onboarding new employees to Ramp.

Create Webhook Subscription

Tool to create a new webhook subscription for receiving event notifications from Ramp.

Deactivate User

Tool to deactivate a user in your Ramp organization.

Delete Accounting GL Account

Tool to delete a general ledger account from Ramp.

Delete Accounting Connection

Tool to disconnect the current active API-based accounting connection.

Delete Custom Accounting Field

Tool to delete a custom accounting field from Ramp.

Delete Accounting Inventory Item Option

Tool to delete an accounting inventory item option from Ramp.

Delete Tax Code Accounting Field

Tool to delete the tax code accounting field from Ramp.

Delete Accounting Tax Code Option

Tool to delete a tax code option from Ramp.

Delete Accounting Tax Rate

Tool to delete an accounting tax rate from Ramp.

Delete Accounting Vendor

Tool to delete an accounting vendor from Ramp.

Delete Custom Field Option

Tool to delete a custom accounting field option from Ramp.

Delete Inventory Item Field

Tool to delete the inventory item accounting field from Ramp.

Remove Users from Shared Limit

Tool to remove users from a shared spend limit in Ramp.

Delete Webhook Subscription

Tool to delete a webhook subscription by ID.

Fetch General Ledger Account

Tool to fetch a specific general ledger account by ID from Ramp.

Fetch Accounting Vendor

Tool to fetch a specific accounting vendor by ID from Ramp.

Fetch Custom Accounting Field

Tool for fetching a custom accounting field.

List General Ledger Accounts

Tool to list general ledger accounts from Ramp.

Fetch All Accounting Connections

Tool to fetch all accounting connections for the current Ramp business.

Get Accounting Connection

Tool to fetch the current active accounting connection for a Ramp account.

Fetch Accounting Connection By ID

Tool to fetch a specific accounting connection by ID from Ramp.

List Custom Accounting Fields

Tool to list custom accounting fields for coding transactions.

List Accounting Vendors

Tool to list accounting vendors from Ramp.

Get All Transactions

Get all the transactions.

Get Card

Tool for retrieving detailed information about a specific card.

Get Card Vault Resource

Tool to fetch a card's sensitive details from the vault.

Get Custom Field Option

Tool to fetch a custom accounting field option by its ID.

Get Department

Tool for retrieving detailed information about a specific department.

Get Inventory Item Field

Tool to fetch inventory item accounting field for the current accounting connection.

Get Memo

Tool to fetch a transaction memo.

Get Reimbursement Details

Tool for retrieving complete details of a specific reimbursement.

Get Spend Limit

Tool to fetch detailed information about a specific spend limit.

Get Statement

Tool for retrieving statement details or downloading statements.

Get Transaction Details

Tool for retrieving complete details of a specific transaction.

Get User

Tool to retrieve detailed information about a specific Ramp user by their ID.

Get Users Deferred Status

Tool for fetching the status of a deferred user task.

Get Vendor Details

Tool for retrieving detailed information about a specific vendor.

Get Webhook

Tool to retrieve detailed information about a specific webhook subscription by ID.

Issue Virtual Card

Tool for issuing virtual cards to users instantly.

List Accounting Inventory Item Options

Tool to list accounting inventory item options from Ramp.

List Accounting Tax Rates

Tool to list tax rates from Ramp's accounting integration.

List All Cards

Tool for listing all cards across the organization with optional filters.

List Departments

Tool for listing all departments in the organization.

List Memos

Tool for listing memos associated with transactions in your Ramp organization.

List Reimbursements

Tool for listing reimbursements with comprehensive filtering options.

List Statements

Tool for listing all statements with filtering options.

List Users

Tool for listing users in your Ramp organization with flexible filtering.

List Vendors

Tool for listing vendors with their spending information.

List Vendor Bank Accounts

Tool for listing bank accounts associated with a specific vendor.

List Vendor Contacts

Tool for listing contacts associated with a specific vendor.

List Vendor Credits

Tool to list all vendor credits for all vendors of a business.

List Webhooks

Tool for listing all webhook subscriptions for the organization.

Options for Custom Accounting Field

Tool for listing options for a given accounting field.

Update Accounting Connection

Tool to update an accounting connection's settings.

Update Card

Tool to update a card's properties including owner, display name, and spending restrictions.

Update Custom Field Option

Tool to update a custom accounting field option.

Update General Ledger Account

Tool to update a general ledger account in Ramp.

Update Inventory Item Field

Tool to update the inventory item accounting field for a Ramp connection.

Upload Accounting GL Accounts

Tool to batch upload general ledger accounts to Ramp.

Create Accounting Connection

Tool to register a new API-based accounting connection between Ramp and an accounting provider.

Upload Accounting Vendors

Tool to batch upload vendors to Ramp for coding transactions, bills, and purchase orders.

Upload Inventory Item Options

Tool to upload inventory item options for an active inventory item accounting field.

Create Physical Card

Tool to create a physical card asynchronously.

Reactivate Accounting Connection

Tool to reactivate a previously unlinked accounting connection by changing its status back to linked.

Reactivate User

Tool to reactivate a suspended user in your Ramp organization.

Submit Reimbursement Receipt

Tool to upload a receipt for a reimbursement.

Suspend Card

Tool to suspend a card by creating an async task that locks the card from use.

Terminate Card

Tool to permanently terminate a Ramp card.

Update Custom Accounting Field

Tool to update a custom accounting field.

Update Accounting Inventory Item Option

Tool to update an inventory item option in Ramp's accounting system.

Update Accounting Tax Code

Tool to update tax code accounting field.

Update Accounting Tax Code Option

Tool to update a tax code option in Ramp.

Update Accounting Tax Rate

Tool to update an accounting tax rate in Ramp.

Update Accounting Vendor

Tool to update an accounting vendor in Ramp.

Update Card Spending Limit

Tool for updating spending limits on a card.

Update Department

Tool for updating an existing department in your Ramp organization.

Update Spending Limit

Tool to update a spending limit in Ramp.

Update User

Tool to update an existing user in your Ramp organization.

Upload New Options for Custom Accounting Field

Tool for uploading new options for a given accounting field.

Upload Tax Code Options

Tool to upload tax code options to Ramp.

Upload Accounting Tax Rates

Tool to batch upload tax rates to Ramp.

FAQ

Frequently asked questions

With a standalone Ramp MCP server, the agents and LLMs can only access a fixed set of Ramp tools tied to that server. However, with the Composio Tool Router, agents can dynamically load tools from Ramp and many other apps based on the task at hand, all through a single MCP endpoint.

Yes, you can. LlamaIndex fully supports MCP integration. You get structured tool calling, message history handling, and model orchestration while Tool Router takes care of discovering and serving the right Ramp tools.

Yes, absolutely. You can configure which Ramp scopes and actions are allowed when connecting your account to Composio. You can also bring your own OAuth credentials or API configuration so you keep full control over what the agent can do.

All sensitive data such as tokens, keys, and configuration is fully encrypted at rest and in transit. Composio is SOC 2 Type 2 compliant and follows strict security practices so your Ramp data and credentials are handled as safely as possible.

Start with Ramp.It takes 30 seconds.

Managed auth, hosted MCP servers, and every Ramp tool your agent needs.Free to start.

Start building