How to integrate Fidel api MCP with OpenAI Agents SDK

This guide walks you through connecting Fidel api to the OpenAI Agents SDK using the Composio tool router. By the end, you'll have a working Fidel api agent that can register a new loyalty program for our stores, create a webhook for real-time offer updates, fetch details of a specific payment brand through natural language commands. This guide will help you understand how to give your OpenAI Agents SDK agent real control over a Fidel api account through Composio's Fidel api MCP server. Before we dive in, let's take a quick look at the key ideas and tools involved.

Fidel api logoFidel api
Api Key

Fidel api is a secure platform for linking payment cards to web and mobile apps. It enables real-time card transaction monitoring and event-based automation for businesses.

39 Tools

Introduction

This guide walks you through connecting Fidel api to the OpenAI Agents SDK using the Composio tool router. By the end, you'll have a working Fidel api agent that can register a new loyalty program for our stores, create a webhook for real-time offer updates, fetch details of a specific payment brand through natural language commands.

This guide will help you understand how to give your OpenAI Agents SDK agent real control over a Fidel api account through Composio's Fidel api MCP server.

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

Also integrate Fidel api with

TL;DR

Here's what you'll learn:
  • Get and set up your OpenAI and Composio API keys
  • Install the necessary dependencies
  • Initialize Composio and create a Tool Router session for Fidel api
  • Configure an AI agent that can use Fidel api as a tool
  • Run a live chat session where you can ask the agent to perform Fidel api operations

What is OpenAI Agents SDK?

The OpenAI Agents SDK is a lightweight framework for building AI agents that can use tools and maintain conversation state. It provides a simple interface for creating agents with hosted MCP tool support.

Key features include:

  • Hosted MCP Tools: Connect to external services through hosted MCP endpoints
  • SQLite Sessions: Persist conversation history across interactions
  • Simple API: Clean interface with Agent, Runner, and tool configuration
  • Streaming Support: Real-time response streaming for interactive applications

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

The Fidel api MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your Fidel api account. It provides structured and secure access to your Fidel API tools, so your agent can perform actions like creating brands, managing programs, retrieving offers, handling webhooks, and more on your behalf.

  • Brand and program creation: Easily instruct your agent to register new brands or set up loyalty programs for your business, streamlining onboarding and expansion.
  • Real-time webhook management: Let your agent create or delete webhooks so you can receive instant notifications for important program events without manual setup.
  • Detailed entity retrieval: Have your agent fetch comprehensive details about brands, programs, offers, or webhooks whenever you need insights or verification.
  • Offer and webhook deletion: Direct your agent to remove outdated offers or webhooks, keeping your Fidel API environment clean and up-to-date.
  • End-to-end automation for payment integrations: Allow your agent to manage the full lifecycle of brands, programs, and event hooks, helping you build seamless payment-linked experiences with minimal effort.

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 step09 STEPS
1

Prerequisites

Before starting, make sure you have:
  • Composio API Key and OpenAI API Key
  • Primary know-how of OpenAI Agents SDK
  • A live Fidel api project
  • Some knowledge of Python or Typescript
2

Getting API Keys for OpenAI and Composio

OpenAI API Key
  • Go to the OpenAI dashboard and create an API key. You'll need credits to use the models, or you can connect to another model provider.
  • Keep the API key safe.
Composio API Key
3

Install dependencies

npm install @composio/openai-agents @openai/agents dotenv

Install the Composio SDK and the OpenAI Agents SDK.

4

Set up environment variables

bash
OPENAI_API_KEY=sk-...your-api-key
COMPOSIO_API_KEY=your-api-key
USER_ID=composio_user@gmail.com

Create a .env file and add your OpenAI and Composio API keys.

5

Import dependencies

import 'dotenv/config';
import { Composio } from '@composio/core';
import { OpenAIAgentsProvider } from '@composio/openai-agents';
import { Agent, hostedMcpTool, run, OpenAIConversationsSession } from '@openai/agents';
import * as readline from 'readline';
What's happening:
  • You're importing all necessary libraries.
  • The Composio and OpenAIAgentsProvider classes are imported to connect your OpenAI agent to Composio tools like Fidel api.
6

Set up the Composio instance

dotenv.config();

const composioApiKey = process.env.COMPOSIO_API_KEY;
const userId = process.env.USER_ID;

if (!composioApiKey) {
  throw new Error('COMPOSIO_API_KEY is not set. Create a .env file with COMPOSIO_API_KEY=your_key');
}
if (!userId) {
  throw new Error('USER_ID is not set');
}

// Initialize Composio
const composio = new Composio({
  apiKey: composioApiKey,
  provider: new OpenAIAgentsProvider(),
});
What's happening:
  • dotenv.config() loads your .env file so COMPOSIO_API_KEY and USER_ID are available as environment variables.
  • Creating a Composio instance using the API Key and OpenAIAgentsProvider class.
7

Create a Tool Router session

// Create Tool Router session for Fidel api
const session = await composio.create(userId as string, {
  toolkits: ['fidel_api'],
});
const mcpUrl = session.mcp.url;

What is happening:

  • You give the Tool Router the user id and the toolkits you want available. Here, it is only fidel_api.
  • The router checks the user's Fidel api connection and prepares the MCP endpoint.
  • The returned session.mcp.url is the MCP URL that your agent will use to access Fidel api.
  • This approach keeps things lightweight and lets the agent request Fidel api tools only when needed during the conversation.
8

Configure the agent

// Configure agent with MCP tool
const agent = new Agent({
  name: 'Assistant',
  model: 'gpt-5',
  instructions:
    'You are a helpful assistant that can access Fidel api. Help users perform Fidel api operations through natural language.',
  tools: [
    hostedMcpTool({
      serverLabel: 'tool_router',
      serverUrl: mcpUrl,
      headers: { 'x-api-key': composioApiKey },
      requireApproval: 'never',
    }),
  ],
});
What's happening:
  • We're creating an Agent instance with a name, model (gpt-5), and clear instructions about its purpose.
  • The agent's instructions tell it that it can access Fidel api and help with queries, inserts, updates, authentication, and fetching database information.
  • The tools array includes a hostedMcpTool that connects to the MCP server URL we created earlier.
  • The headers object includes the Composio API key for secure authentication with the MCP server.
  • requireApproval: 'never' means the agent can execute Fidel api operations without asking for permission each time, making interactions smoother.
9

Start chat loop and handle conversation

// Keep conversation state across turns
const conversationSession = new OpenAIConversationsSession();

// Simple CLI
const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout,
  prompt: 'You: ',
});

console.log('\nComposio Tool Router session created.');
console.log('\nChat started. Type your requests below.');
console.log("Commands: 'exit', 'quit', or 'q' to end\n");

try {
  const first = await run(agent, 'What can you help me with?', { session: conversationSession });
  console.log(`Assistant: ${first.finalOutput}\n`);
} catch (e) {
  console.error('Error:', e instanceof Error ? e.message : e, '\n');
}

rl.prompt();

rl.on('line', async (userInput) => {
  const text = userInput.trim();

  if (['exit', 'quit', 'q'].includes(text.toLowerCase())) {
    console.log('Goodbye!');
    rl.close();
    process.exit(0);
  }

  if (!text) {
    rl.prompt();
    return;
  }

  try {
    const result = await run(agent, text, { session: conversationSession });
    console.log(`\nAssistant: ${result.finalOutput}\n`);
  } catch (e) {
    console.error('Error:', e instanceof Error ? e.message : e, '\n');
  }

  rl.prompt();
});

rl.on('close', () => {
  console.log('\n👋 Session ended.');
  process.exit(0);
});
What's happening:
  • The program prints a session URL that you visit to authorize Fidel api.
  • After authorization, the chat begins.
  • Each message you type is processed by the agent using run().
  • The responses are printed to the console.
  • Typing exit, quit, or q cleanly ends the chat.

Complete Code

Here's the complete code to get you started with Fidel api and OpenAI Agents SDK:

import 'dotenv/config';
import { Composio } from '@composio/core';
import { OpenAIAgentsProvider } from '@composio/openai-agents';
import { Agent, hostedMcpTool, run, OpenAIConversationsSession } from '@openai/agents';
import * as readline from 'readline';

const composioApiKey = process.env.COMPOSIO_API_KEY;
const userId = process.env.USER_ID;

if (!composioApiKey) {
  throw new Error('COMPOSIO_API_KEY is not set. Create a .env file with COMPOSIO_API_KEY=your_key');
}
if (!userId) {
  throw new Error('USER_ID is not set');
}

// Initialize Composio
const composio = new Composio({
  apiKey: composioApiKey,
  provider: new OpenAIAgentsProvider(),
});

async function main() {
  // Create Tool Router session
  const session = await composio.create(userId as string, {
    toolkits: ['fidel_api'],
  });
  const mcpUrl = session.mcp.url;

  // Configure agent with MCP tool
  const agent = new Agent({
    name: 'Assistant',
    model: 'gpt-5',
    instructions:
      'You are a helpful assistant that can access Fidel api. Help users perform Fidel api operations through natural language.',
    tools: [
      hostedMcpTool({
        serverLabel: 'tool_router',
        serverUrl: mcpUrl,
        headers: { 'x-api-key': composioApiKey },
        requireApproval: 'never',
      }),
    ],
  });

  // Keep conversation state across turns
  const conversationSession = new OpenAIConversationsSession();

  // Simple CLI
  const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout,
    prompt: 'You: ',
  });

  console.log('\nComposio Tool Router session created.');
  console.log('\nChat started. Type your requests below.');
  console.log("Commands: 'exit', 'quit', or 'q' to end\n");

  try {
    const first = await run(agent, 'What can you help me with?', { session: conversationSession });
    console.log(`Assistant: ${first.finalOutput}\n`);
  } catch (e) {
    console.error('Error:', e instanceof Error ? e.message : e, '\n');
  }

  rl.prompt();

  rl.on('line', async (userInput) => {
    const text = userInput.trim();

    if (['exit', 'quit', 'q'].includes(text.toLowerCase())) {
      console.log('Goodbye!');
      rl.close();
      process.exit(0);
    }

    if (!text) {
      rl.prompt();
      return;
    }

    try {
      const result = await run(agent, text, { session: conversationSession });
      console.log(`\nAssistant: ${result.finalOutput}\n`);
    } catch (e) {
      console.error('Error:', e instanceof Error ? e.message : e, '\n');
    }

    rl.prompt();
  });

  rl.on('close', () => {
    console.log('\nSession ended.');
    process.exit(0);
  });
}

main().catch((err) => {
  console.error('Fatal error:', err);
  process.exit(1);
});

Conclusion

This was a starter code for integrating Fidel api MCP with OpenAI Agents SDK to build a functional AI agent that can interact with Fidel api.

Key features:

  • Hosted MCP tool integration through Composio's Tool Router
  • SQLite session persistence for conversation history
  • Simple async chat loop for interactive testing
You can extend this by adding more toolkits, implementing custom business logic, or building a web interface around the agent.
TOOLS

Supported Tools

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

Create Brand

Create a new brand in Fidel API.

Create Brand Webhook

Tool to create a webhook at the brand level for receiving real-time event notifications.

Create Location

Create a new location for a program in Fidel API.

Create MID Request

Tool to create a new MID (Merchant ID) request for a specific program and location.

Create Offer

Create a new offer in Fidel API.

Create Program

Creates a new card-linked loyalty program in Fidel.

Create Program Webhook

Tool to register a new webhook for program-related events.

Delete Location

Tool to delete a location by its ID.

Delete Offer

Tool to delete a specified offer by its ID.

Delete Program Webhook

Permanently deletes a webhook by its ID.

Get Brand

Tool to retrieve information about a specific brand.

Get Location

Tool to retrieve details of a specific location by its ID.

Get MID

Tool to retrieve details of a specific MID (Merchant ID).

Get MID Request

Tool to retrieve details of a specific MID request.

Get Offer

Retrieves detailed information about a specific offer by its unique ID.

Get Program

Tool to retrieve details of a specific program.

Get Transaction

Tool to retrieve details of a specific transaction by its ID.

Get Webhook

Retrieve details of a specific webhook by its unique identifier.

Link All Program Locations to Offer

Tool to link all brand locations in a program to an offer.

Link Location to Offer

Link a location to an offer in Fidel API.

List Brands

Retrieves a paginated list of all brands associated with your Fidel API account.

List Cards

List all payment cards linked to a Fidel program.

List Cards By Metadata

Tool to list payment cards filtered by metadata ID.

List Cards with Active Offer

List all payment cards that have activated a specific offer.

List Locations

Tool to list all locations for a program.

List Locations by Brand

Tool to list all locations for a specific brand within a program.

List Locations by Offer

Tool to list all locations linked to a specific offer.

List MID Requests

List all MID (Merchant ID) requests for a specific program.

List MIDs

Tool to list all MIDs (Merchant IDs) for a program.

List Missing Transaction Requests

Tool to list all missing transaction requests for a specific program.

List Offers

List all offers in the Fidel API.

List Programs

List all Fidel programs in your account.

List Program Webhooks

Tool to list all registered webhooks for a specific program.

List Transactions

List transactions for a Fidel program with optional filtering and pagination.

Unlink Location From Offer

Tool to unlink a location from an offer by removing the location association.

Update Brand

Update an existing brand's details in Fidel API.

Update Offer

Updates specific properties of an existing offer.

Update Program

Updates a Fidel API program's properties.

Update Webhook

Tool to update an existing webhook's configuration.

FAQ

Frequently asked questions

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

Yes, you can. OpenAI Agents SDK 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 Fidel api tools.

Yes, absolutely. You can configure which Fidel api 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 Fidel api data and credentials are handled as safely as possible.

Start with Fidel api.It takes 30 seconds.

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

Start building