How to integrate Metabase MCP with OpenAI Agents SDK

GET STARTED FOR FREE
Framework Integration Gradient
Metabase Logo
open-ai-agents-sdk Logo
divider

Introduction

This guide walks you through connecting Metabase to the OpenAI Agents SDK using the Composio tool router. By the end, you'll have a working Metabase agent that can get all charts from marketing dashboard, run sql query for revenue last quarter, share dashboard link with analytics team through natural language commands.

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

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

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 Metabase
  • Configure an AI agent that can use Metabase as a tool
  • Run a live chat session where you can ask the agent to perform Metabase operations

What is open-ai-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 Metabase MCP server, and what's possible with it?

The Metabase MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your Metabase account. It provides structured and secure access so your agent can perform Metabase operations on your behalf.

Supported Tools & Triggers

Tools
Create BookmarkTool to create a new bookmark for a Metabase item (card, dashboard, collection, or dataset).
Create BookmarkTool to create a new bookmark for a Metabase item (card, dashboard, collection, or dataset).
Run Card Pivot QueryTool to run a pivot table query on a Metabase card (question).
Run Card QueryTool to run the query associated with a Card and return its results.
Copy DashboardTool to create a copy of an existing Metabase dashboard.
Run Dashboard Pivot DashCard QueryTool to run a pivot table query for a specific DashCard.
Save Dashboard to CollectionTool to save a denormalized dashboard description into a collection.
Discard Database Field ValuesTool to discard all saved field values for a specific database.
Dismiss Database Sync SpinnerTool to manually set the initial sync status of a Database and corresponding tables to complete.
Trigger Database Field Values RescanTool to trigger a manual scan of field values for a Database.
Trigger Database Schema SyncTool to trigger a manual update of the schema metadata for a Database.
Search Dataset Parameter ValuesTool to search for parameter values in datasets when editing cards or dashboards.
Create Field DimensionTool to set the dimension for a field at the specified ID in Metabase.
Discard Field ValuesTool to discard the FieldValues belonging to a Metabase field.
Update Field ValuesTool to update field values and human-readable values for a Field whose semantic type is category/city/state/country or whose base type is type/Boolean.
Unpersist CardTool to unpersist a Metabase card/model.
Disable Database Model PersistenceTool to disable model persistence for a Metabase database.
Discard Table Field ValuesTool to discard the FieldValues belonging to the Fields in a Metabase Table.
Rescan Table Field ValuesTool to manually trigger an update for FieldValues for Fields belonging to a specific Table.
Sync Table SchemaTool to trigger a manual update of the schema metadata for a specific Table.
Delete ActionTool to delete an Action from Metabase.
Delete ActionTool to delete a Metabase action by its ID.
Delete BookmarkTool to delete a bookmark from a Metabase item (card, dashboard, or collection).
Delete API CacheTool to delete/clear cached data in Metabase for specific entities.
Delete CardTool to delete a Metabase card (question) by its ID.
Delete DashboardTool to delete a Metabase dashboard by its ID.
Delete Model IndexTool to delete a Metabase model index by its ID.
Delete Timeline EventTool to delete a timeline event by ID.
Delete TimelineTool to delete a timeline by ID.
Delete User Key-ValueTool to delete a user key-value pair from Metabase.
Delete BookmarkTool to delete a bookmark by model and ID.
Delete CardTool to hard delete a Metabase card.
Delete DashboardTool to hard delete a Metabase dashboard by its ID.
Delete User SubscriptionsTool to delete all Alert and DashboardSubscription subscriptions for a User.
Delete Field DimensionTool to remove the dimension associated with a field at the specified ID.
Delete Glossary EntryTool to delete a glossary entry from Metabase.
Delete Glossary ItemTool to delete a glossary item by ID.
Delete Model IndexTool to delete a ModelIndex by ID from Metabase.
Delete TimelineTool to delete a Metabase timeline and cascade delete all its associated events.
Delete Timeline EventTool to delete a Metabase timeline event.
Delete User Key-Value PairTool to delete a user key-value pair by namespace and key.
Delete User SubscriptionsTool to delete all Alert and DashboardSubscription subscriptions for a User.
Get ActionTool to retrieve a Metabase action by ID.
Get Action Execute ParametersTool to fetch values for filling in action execution parameters.
Get all Metabase actionsTool to retrieve all actions available in the Metabase instance.
Get Popular ItemsTool to get the list of 5 popular items on the Metabase instance.
Get Recent Activity ViewsTool to retrieve recently viewed items in Metabase.
Get All AlertsTool to retrieve all alerts in Metabase.
Get Automagic Dashboard CandidatesTool to retrieve automagic dashboard candidates for a specific database.
Get Automagic Dashboard Cell AnalysisTool to return an automagic dashboard analyzing a specific cell in an entity's data.
Get Automagic Dashboard Cell Rule AnalysisTool to fetch an automagic dashboard analyzing a specific cell using a template rule.
Get Automagic Dashboard Query MetadataTool to retrieve all metadata for an automagic dashboard for the specified entity type and ID.
Get Automagic Dashboard with Rule and TemplateTool to retrieve an automagic dashboard for a specified entity using a specific rule prefix and dashboard template.
Get User BookmarksTool to retrieve all bookmarks for the authenticated user.
Get API CardTool to list all cards (questions) available to the authenticated user in Metabase.
Search Card Parameter ValuesTool to search for values of a specific parameter in a Metabase card.
Get Card by IDTool to retrieve a specific card (question) by its ID.
Get Card DashboardsTool to get a list of dashboards containing a specific card.
Get Card SeriesTool to retrieve series data for a specific card.
Get all collectionsTool to retrieve all collections that the current user has read permissions for.
Get Collection by IDTool to retrieve detailed information about a Metabase collection by its ID.
Get Collection ItemsTool to retrieve items from a specific Metabase collection.
Get Root CollectionTool to fetch the Root Collection and its top-level objects.
Get Collection TreeTool to retrieve the collection tree structure from Metabase.
Get Dashboard Parameter RemappingTool to get parameter remapping for a dashboard parameter value.
Get Dashboard Parameter ValuesTool to fetch available values for a specific dashboard parameter.
Get Dashboard Related EntitiesTool to retrieve related entities for a Metabase dashboard.
Get All DatabasesTool to retrieve a list of all Database instances configured in Metabase.
Get Database DetailsTool to retrieve complete details for a specific database in Metabase.
Get Database Autocomplete SuggestionsTool to retrieve autocomplete suggestions for table and field names in a database.
Get Database Card Autocomplete SuggestionsTool to get card autocomplete suggestions for a specific database in Metabase.
Get Database FieldsTool to retrieve all fields from a specific database in Metabase.
Check Database HealthTool to check the health status of a specific database connection in Metabase.
Get Database MetadataTool to retrieve complete metadata for a specific database including all tables and fields.
Get Virtual Database DatasetsTool to retrieve all datasets from a Metabase virtual database.
Get User Audit InfoTool to get audit info for the current authenticated user.
Get Billing API VersionTool to retrieve the billing API version information for the Metabase Enterprise Edition instance.
Get Resource DependentsTool to get dependents of a resource in Metabase's dependency graph.
Get Embedding Hub ChecklistTool to retrieve the embedding hub checklist status for Metabase Enterprise Edition.
Get Current Remote Sync TaskTool to retrieve the current remote sync task status in Metabase.
Get Stale Data By IDTool to retrieve stale data information by ID from Metabase Enterprise Edition.
Get Uploaded TablesTool to retrieve all uploaded tables in Metabase Enterprise Edition.
Get Field Related EntitiesTool to retrieve related entities for a Metabase field.
Search Field ValuesTool to search for field values in Metabase that start with a given string.
Get Field ValuesTool to retrieve distinct values for a Metabase field.
Get API GlossaryTool to retrieve all glossary items from Metabase.
Get Current User Login HistoryTool to retrieve login history for the currently authenticated user.
Get Model Index ValuesTool to retrieve indexed field values for a specific Metabase model.
Get Model Index DetailsTool to retrieve details of a specific model index by its ID.
Get all native query snippetsTool to retrieve all native query snippets available in the Metabase instance.
Get Native Query Snippet by IDTool to retrieve a specific native query snippet by its ID.
Get NotificationsTool to retrieve notifications from Metabase with optional filtering.
Get Public Card by UUIDTool to fetch a publicly-accessible card by its public UUID and return card information including query definition, visualization settings, and parameters.
Get Public oEmbed MetadataTool to get oEmbed metadata for public Metabase resources.
Get Public Pivot Card QueryTool to fetch a publicly-accessible pivot card and return query results including data rows, column metadata, and query status.
Get All PulsesTool to retrieve all pulses (scheduled reports/subscriptions) in Metabase.
Get Pulse Form Input ConfigurationTool to retrieve configuration information for creating or updating Pulses (scheduled email reports).
Get Pulse by IDTool to retrieve a specific pulse (subscription) by its ID.
Get Pulse Preview CardTool to retrieve the HTML preview of a Metabase card formatted for pulse emails.
Get Pulse Preview Card InfoTool to retrieve preview information for a Metabase card formatted for pulse emails.
Get Pulse Preview DashboardTool to retrieve the pulse preview for a specific dashboard by its ID.
Get Revision by ID and EntityTool to retrieve a specific revision by ID and entity type.
Get Entity Revision HistoryTool to retrieve the revision history for a Metabase entity (dashboard, card, metric, or segment).
Search Metabase objectsTool to search Cards, Dashboards, Collections, Tables, Databases, and Pulses for a substring.
Get Search WeightsTool to retrieve the current search weight configuration for the Metabase instance.
Get All SegmentsTool to retrieve all segments from Metabase.
Validate Password Reset TokenTool to validate a password reset token in Metabase.
Get Session PropertiesTool to retrieve all global session properties and their values that are public.
Get Card Table Foreign KeysTool to retrieve foreign key relationships for a card-based virtual table.
Get Card Virtual Table Query MetadataTool to retrieve metadata for a virtual table created from a card (saved question).
Get Table Foreign KeysTool to retrieve foreign key relationships for a Metabase table.
Get Table Query MetadataTool to retrieve metadata about a table useful for running queries.
Get Table Data by IDTool to retrieve data from a specific Metabase table by ID.
Get All TimelinesTool to retrieve all timelines in Metabase.
Get Collection TimelinesTool to retrieve timelines associated with a specific Metabase collection.
Get Root Collection TimelinesTool to retrieve all timelines associated with the root collection.
Get Timeline EventTool to retrieve a timeline event by ID.
Get Timeline by IDTool to fetch a timeline by its ID from Metabase.
Get Current UserTool to retrieve information about the currently authenticated user.
Get User by IDTool to retrieve a specific user by their ID.
Get User Key-Value by NamespaceTool to retrieve all user key-value pairs for a specified namespace.
Get User RecipientsTool to retrieve users for recipient selection.
Generate Random Security TokenTool to generate a cryptographically secure random token for Metabase.
Get Automagic DashboardTool to generate an automagic dashboard for a given entity.
Get Automagic DashboardTool to retrieve an automagic dashboard for a specified entity with its ID.
Get Automagic Dashboard Cell AnalysisTool to return an automagic dashboard analyzing a specific cell in an entity's data.
Get Automagic Dashboard Cell RuleTool to fetch an automagic dashboard analyzing a specific cell in a table or query.
Get Automagic Dashboards CompareTool to return an automagic comparison dashboard for entity with id compared with comparison-entity with comparison-entity-id-or-query.
Get Automagic Dashboard Query MetadataTool to retrieve all metadata for an automagic dashboard for a specific entity and ID.
Get automagic dashboard by ruleTool to return an automagic dashboard for a specific entity using a dashboard template with rule prefix.
Get Card DashboardsTool to get a list of dashboards that a specific card appears in.
Search Card Parameter ValuesTool to fetch possible values for a card parameter that match a search query.
Get Card Query MetadataTool to get comprehensive query metadata for a Metabase card (saved question).
Get Card SeriesTool to fetch a list of cards compatible as series with a specified card.
Get Collection by IDTool to fetch a specific Metabase collection with standard details added.
Get Collection ItemsTool to fetch items from a specific Metabase collection.
Get Automagic Comparison DashboardTool to retrieve an automagic comparison dashboard comparing a cell in one entity with another entity.
Get Dashboard by IDTool to retrieve details of a specific Metabase dashboard by ID.
Get Dashboard by IDTool to retrieve a dashboard by its ID from Metabase.
Search dashboard parameter valuesTool to search for dashboard parameter values in Metabase.
Get Dashboard Params RemappingTool to fetch the remapped value for a given dashboard parameter in Metabase.
Search Dashboard Parameter ValuesTool to fetch possible values of a dashboard parameter that contain the search query.
Get Dashboard Query MetadataTool to get all of the required query metadata for the cards on a dashboard.
Get Dashboard Related EntitiesTool to retrieve related entities for a Metabase dashboard.
Get Database Autocomplete SuggestionsTool to get autocomplete suggestions for table and field names in a Metabase database.
Get Database By IDTool to retrieve a single database by ID from Metabase.
Get Database Card Autocomplete SuggestionsTool to return a list of Card autocomplete suggestions for a given query in a given Database.
Get Database DatasetsTool to retrieve tables (models and metrics) from a virtual database schema in Metabase.
Get Database FieldsTool to retrieve all field metadata from a Metabase database.
Get Database HealthcheckTool to check if a Metabase database can currently connect.
Get Database MetadataTool to retrieve complete metadata for a specific database including all tables and fields.
Get Database SchemasTool to retrieve all schemas with tables for a specific database in Metabase.
Get Database Settings AvailableTool to get all database-local settings and their availability for a given database.
Get Database Syncable SchemasTool to retrieve all syncable schemas for a specific database in Metabase.
Get Stale Entities from CollectionTool to retrieve stale entities (cards and dashboards) from a Metabase collection that haven't been used recently.
Get Field RemappingTool to fetch remapped field values for a specific field in Metabase.
Get Field SummaryTool to get summary statistics for a Metabase field by its ID.
Get ModelIndex by IDTool to retrieve a ModelIndex by ID.
Get Most Recently Viewed DashboardTool to retrieve the most recently viewed dashboard for the authenticated user.
Get Native Query Snippet by IDTool to retrieve a specific native query snippet by its ID.
Get Pulse Preview CardTool to get HTML rendering of a Metabase card by ID.
Get Pulse Preview Card InfoTool to get JSON object containing HTML rendering of a card and additional information.
Get Dashboard HTML PreviewTool to retrieve an HTML preview rendering of a dashboard.
Get Revision History by IDTool to retrieve the complete revision history for a Metabase entity by its ID.
Get Table By IDTool to retrieve basic table information by ID from Metabase.
Get Table DataTool to retrieve data from a specific table in Metabase.
Get Table Foreign KeysTool to get all foreign keys whose destination is a field that belongs to a specific table.
Get Table Query MetadataTool to get metadata about a Table useful for running queries.
Get Timeline by IDTool to fetch a timeline by its ID.
Get Collection TimelinesTool to fetch timelines associated with a specific Metabase collection.
Get Timeline EventTool to fetch a timeline event by ID.
Get User by IDTool to fetch a Metabase user by their ID.
Get User Key-Value SettingTool to retrieve a user-specific key-value pair from Metabase storage.
Get All User Key-Values in NamespaceTool to retrieve all key-value pairs in a given namespace for the current user.
Get User Key-Value SettingTool to retrieve a user-specific key-value pair from Metabase storage.
Record Recent ActivityTool to record recent activity for a Metabase item.
Create BookmarkTool to create a bookmark for a Metabase item (card, dashboard, or collection).
Create CardTool to create a new Metabase card (question or model).
Execute Card QueryTool to execute a query for a saved Metabase card/question and retrieve results.
Bulk Move Cards to CollectionTool to bulk move multiple Metabase cards into a target collection or remove them from collections.
Copy CardTool to create a copy of an existing Metabase card (question) by its ID.
Execute Pivot Card QueryTool to execute a pivot query on a Metabase card and return the results.
Get Card Dashboard AssociationsTool to retrieve dashboard associations for given card IDs.
Bulk Move CardsTool to bulk move cards to a collection or remove them from collections.
Create CollectionTool to create a new Metabase collection for organizing content.
Create DashboardTool to create a new Metabase dashboard.
Copy DashboardTool to copy an existing Metabase dashboard.
Execute Dashboard Pivot QueryTool to execute a pivot table query for a specific card on a dashboard.
Create Dashboard in CollectionTool to create a new dashboard in a specific Metabase collection.
Discard Database Field ValuesTool to discard all saved field values for a specific database.
Dismiss Database SpinnerTool to dismiss the spinner for a specific database.
Rescan Database Field ValuesTool to trigger a manual rescan of field values for a specific database.
Sync Database SchemaTool to trigger a schema synchronization for a specific database.
Execute Dataset QueryTool to execute a query against a Metabase database and retrieve results.
Convert Query to Native SQLTool to convert a Metabase query to native SQL format.
Remap Dataset Parameter ValueTool to remap dataset parameter values in Metabase.
Get Dataset Parameter ValuesTool to fetch parameter values for dataset fields in Metabase.
Execute Pivot Table QueryTool to execute a pivot table query and retrieve results.
Get Dataset Query MetadataTool to retrieve query metadata for a dataset query including databases, tables, fields, and snippets.
Check Snippet DependenciesTool to check dependencies for a native query snippet in Metabase Enterprise Edition.
Create Dashboard SubscriptionTool to create a dashboard subscription using Metabot tools.
Filter RecordsTool to filter records from a Metabase data source using metabot tools.
Generate InsightsTool to generate insights for a table using Metabot tools.
Get Current UserTool to retrieve information about the current authenticated user in a Metabase metabot conversation.
Get Dashboard DetailsTool to retrieve dashboard details for a Metabase metabot conversation.
Get Document Details via MetabotTool to retrieve document details using Metabase metabot tools.
Get Query DetailsTool to get query details using Metabot tools API.
Get Snippet DetailsTool to retrieve SQL snippet details via Metabase metabot tools.
Get Metabot SnippetsTool to retrieve SQL snippets for a Metabase metabot conversation.
Get Table DetailsTool to retrieve comprehensive table details via Metabase metabot tools.
Query Datasource via MetabotTool to query a Metabase datasource using Metabot tools.
Metabot SearchTool to search Metabase entities using the metabot search API.
Search Metabase Items (Metabot V2)Tool to search Metabase items using the Metabot search v2 endpoint.
Cancel Current Remote Sync TaskTool to cancel the current active Remote Sync task in Metabase Enterprise Edition.
Translate Entity IDsTool to translate Metabase entity IDs (21-character strings) to their numeric IDs.
Discard Field ValuesTool to discard cached FieldValues for a specific field.
Rescan Field ValuesTool to manually trigger an update for the FieldValues for a specific field.
Create Glossary EntryTool to create a new glossary entry in Metabase.
Create Model IndexTool to create a new model index in Metabase.
Create native query snippetTool to create a new native query snippet in Metabase.
Create NotificationTool to create a new notification in Metabase.
Send NotificationTool to trigger sending an unsaved notification in Metabase.
Unpersist CardTool to unpersist a Metabase card by its ID.
Unpersist DatabaseTool to disable model persistence for a specific database.
Submit Product FeedbackTool to submit product feedback to Metabase.
Create PulseTool to create a new pulse (scheduled report/subscription) in Metabase.
Revert Entity to Previous RevisionTool to revert a Metabase entity (card, dashboard, document, or segment) to a previous revision.
Send Password Reset EmailTool to send a password reset email when user has forgotten their password.
Check Password ComplexityTool to check if a password meets Metabase's configured password complexity rules.
Submit Bug Report to SlackTool to submit a bug report to Slack via Metabase's bug reporting endpoint.
Discard Table Field ValuesTool to discard cached FieldValues for all Fields belonging to a specific Table.
Rescan Table Field ValuesTool to trigger a manual rescan of field values for a specific table.
Sync Table SchemaTool to trigger a manual update of the schema metadata for a specific Table.
Create TimelineTool to create a new timeline in Metabase.
Execute Dashboard Card QueryTool to execute a query for a specific card within a dashcard on a dashboard.
Update Action by IDTool to update an existing Metabase action by its ID.
Update Bookmark OrderingTool to update the order of bookmarks for the authenticated user.
Update Card by IDTool to update a specific card (question) by its ID.
Update Collection by IDTool to update an existing Metabase collection by its ID.
Update DashboardTool to update a Metabase dashboard by its ID.
Update Dashboard CardsTool to update dashboard cards and tabs.
Update Database ConfigurationTool to update a database configuration in Metabase.
Update Field MetadataTool to update a Metabase field by its ID.
Update Glossary Entry by IDTool to update an existing glossary entry in Metabase by its ID.
Update Native Query Snippet by IDTool to update an existing native query snippet by its ID.
Update Pulse by IDTool to update an existing pulse (scheduled report/subscription) by ID.
Update Search WeightsTool to update search weights configuration in Metabase.
Update Table MetadataTool to update a Metabase table by its ID.
Update Table MetadataTool to update a Metabase table metadata by its ID.
Update Table Field Display OrderTool to update the display order of fields in a Metabase table.
Update Timeline Event by IDTool to update an existing timeline event by its ID.
Update Timeline by IDTool to update an existing timeline by its ID.
Update User by IDTool to update an existing Metabase user by their ID.
Update ActionTool to update an existing Action in Metabase.
Update CollectionTool to update an existing Metabase collection.
Update DashboardTool to update a Metabase dashboard by ID.
Update Dashboard Cards (Deprecated)Tool to bulk update dashboard cards and tabs.
Update DatabaseTool to update a Database in Metabase.
Update Field MetadataTool to update metadata for a Metabase field by its ID.
Update Glossary EntryTool to update an existing glossary entry in Metabase.
Update Native Query SnippetTool to update an existing native query snippet by ID.
Update PulseTool to update an existing pulse (scheduled report/subscription) by ID.
Update Table by IDTool to update a Table in Metabase by its ID.
Update Table Fields OrderTool to reorder fields in a Metabase table.
Update TimelineTool to update a Metabase timeline by its ID.
Update Timeline EventTool to update an existing Metabase timeline event by its ID.

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

What is Tool Router?

Composio's Tool Router 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 Tool Router

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

How the Tool Router works

The Tool Router 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

Prerequisites

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

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

Install dependencies

pip install composio_openai_agents openai-agents python-dotenv

Install the Composio SDK and the OpenAI Agents SDK.

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.

Import dependencies

import asyncio
import os
from dotenv import load_dotenv

from composio import Composio
from composio_openai_agents import OpenAIAgentsProvider
from agents import Agent, Runner, HostedMCPTool, SQLiteSession
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 Metabase.

Set up the Composio instance

load_dotenv()

api_key = os.getenv("COMPOSIO_API_KEY")
user_id = os.getenv("USER_ID")

if not api_key:
    raise RuntimeError("COMPOSIO_API_KEY is not set. Create a .env file with COMPOSIO_API_KEY=your_key")

# Initialize Composio
composio = Composio(api_key=api_key, provider=OpenAIAgentsProvider())
What's happening:
  • load_dotenv() loads your .env file so OPENAI_API_KEY and COMPOSIO_API_KEY are available as environment variables.
  • Creating a Composio instance using the API Key and OpenAIAgentsProvider class.

Create a Tool Router session

# Create a Metabase Tool Router session
session = composio.create(
    user_id=user_id,
    toolkits=["metabase"]
)

mcp_url = session.mcp.url

What is happening:

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

Configure the agent

# Configure agent with MCP tool
agent = Agent(
    name="Assistant",
    model="gpt-5",
    instructions=(
        "You are a helpful assistant that can access Metabase. "
        "Help users perform Metabase operations through natural language."
    ),
    tools=[
        HostedMCPTool(
            tool_config={
                "type": "mcp",
                "server_label": "tool_router",
                "server_url": mcp_url,
                "headers": {"x-api-key": api_key},
                "require_approval": "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 Metabase 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 dict includes the Composio API key for secure authentication with the MCP server.
  • require_approval: 'never' means the agent can execute Metabase operations without asking for permission each time, making interactions smoother.

Start chat loop and handle conversation

print("\nComposio Tool Router session created.")

chat_session = SQLiteSession("conversation_openai_toolrouter")

print("\nChat started. Type your requests below.")
print("Commands: 'exit', 'quit', or 'q' to end\n")

async def main():
    try:
        result = await Runner.run(
            agent,
            "What can you help me with?",
            session=chat_session
        )
        print(f"Assistant: {result.final_output}\n")
    except Exception as e:
        print(f"Error: {e}\n")

    while True:
        user_input = input("You: ").strip()
        if user_input.lower() in {"exit", "quit", "q"}:
            print("Goodbye!")
            break

        result = await Runner.run(
            agent,
            user_input,
            session=chat_session
        )
        print(f"Assistant: {result.final_output}\n")

asyncio.run(main())
What's happening:
  • The program prints a session URL that you visit to authorize Metabase.
  • After authorization, the chat begins.
  • Each message you type is processed by the agent using Runner.run().
  • The responses are printed to the console, and conversations are saved locally using SQLite.
  • Typing exit, quit, or q cleanly ends the chat.

Complete Code

Here's the complete code to get you started with Metabase and open-ai-agents-sdk:

import asyncio
import os
from dotenv import load_dotenv

from composio import Composio
from composio_openai_agents import OpenAIAgentsProvider
from agents import Agent, Runner, HostedMCPTool, SQLiteSession

load_dotenv()

api_key = os.getenv("COMPOSIO_API_KEY")
user_id = os.getenv("USER_ID")

if not api_key:
    raise RuntimeError("COMPOSIO_API_KEY is not set. Create a .env file with COMPOSIO_API_KEY=your_key")

# Initialize Composio
composio = Composio(api_key=api_key, provider=OpenAIAgentsProvider())

# Create Tool Router session
session = composio.create(
    user_id=user_id,
    toolkits=["metabase"]
)
mcp_url = session.mcp.url

# Configure agent with MCP tool
agent = Agent(
    name="Assistant",
    model="gpt-5",
    instructions=(
        "You are a helpful assistant that can access Metabase. "
        "Help users perform Metabase operations through natural language."
    ),
    tools=[
        HostedMCPTool(
            tool_config={
                "type": "mcp",
                "server_label": "tool_router",
                "server_url": mcp_url,
                "headers": {"x-api-key": api_key},
                "require_approval": "never",
            }
        )
    ],
)

print("\nComposio Tool Router session created.")

chat_session = SQLiteSession("conversation_openai_toolrouter")

print("\nChat started. Type your requests below.")
print("Commands: 'exit', 'quit', or 'q' to end\n")

async def main():
    try:
        result = await Runner.run(
            agent,
            "What can you help me with?",
            session=chat_session
        )
        print(f"Assistant: {result.final_output}\n")
    except Exception as e:
        print(f"Error: {e}\n")

    while True:
        user_input = input("You: ").strip()
        if user_input.lower() in {"exit", "quit", "q"}:
            print("Goodbye!")
            break

        result = await Runner.run(
            agent,
            user_input,
            session=chat_session
        )
        print(f"Assistant: {result.final_output}\n")

asyncio.run(main())

Conclusion

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

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.

How to build Metabase MCP Agent with another framework

Claude Agent SDK

Claude Agent SDK

Use Metabase MCP with Claude Agent SDK

Google ADK

Google ADK

Use Metabase MCP with Google ADK

LangChain

LangChain

Use Metabase MCP with LangChain

Vercel AI SDK

Vercel AI SDK

Use Metabase MCP with Vercel AI SDK

Mastra AI

Mastra AI

Use Metabase MCP with Mastra AI

LlamaIndex

LlamaIndex

Use Metabase MCP with LlamaIndex

CrewAI

CrewAI

Use Metabase MCP with CrewAI

Claude Code

Claude Code

Use Metabase MCP with Claude Code

Codex

Codex

Use Metabase MCP with Codex

FAQ

What are the differences in Tool Router MCP and Metabase MCP?

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

Can I use Tool Router MCP with OpenAI Agents SDK?

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 Metabase tools.

Can I manage the permissions and scopes for Metabase while using Tool Router?

Yes, absolutely. You can configure which Metabase 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.

How safe is my data with Composio Tool Router?

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 Metabase data and credentials are handled as safely as possible.

Used by agents from

Context
Letta
glean
HubSpot
Agent.ai
Altera
DataStax
Entelligence
Rolai
Context
Letta
glean
HubSpot
Agent.ai
Altera
DataStax
Entelligence
Rolai
Context
Letta
glean
HubSpot
Agent.ai
Altera
DataStax
Entelligence
Rolai

Never worry about agent reliability

We handle tool reliability, observability, and security so you never have to second-guess an agent action.

Book a call↗Get started for free