Use OpenAI Agents SDK with Marrow MCP

This tutorial shows how to build a small TypeScript agent with the OpenAI Agents JS SDK and connect it to Marrow MCP. The sample app does one practical job: it uses Marrow advertising data, downloads the export file, loads it into DuckDB and writes a JSON file with improved Amazon listing copy.

What you will build

By the end, you will have a simple agent that:

connects to Marrow MCP with hostedMcpTool
downloads an export file before the URL expires
loads the data into DuckDB and runs SQL over it
produces one final JSON file in response/

Prerequisites

Completion of the Marrow MCP Overview setup, with an MCP key
An OpenAI API key with access to gpt-5.4-mini
Node.js 24 or later (required for native TypeScript support)
yarn (bundled through Corepack; run corepack enable if needed)

Step 1: Clone and install the repository

Install the project:

git clone https://github.com/Deltologic/marrow-mcp-openai-agents-sdk.git
cd marrow-mcp-openai-agents-sdk
yarn install

Step 2: Configure your keys

Copy the environment file and add both API keys:

cp .env.example .env

Open .env and set:

MARROW_MCP_KEY: your MCP key from the Marrow integrations page
OPENAI_API_KEY: your OpenAI API key

The agent already knows how to reach Marrow MCP. In src/index.ts, it uses this configuration:

hostedMcpTool({
    serverLabel: 'marrow',
    serverUrl: 'https://mcp.marrow.com/mcp/v1',
    headers: {
        'marrow-mcp-key': process.env.MARROW_MCP_KEY ?? ''
    }
});

This is the only MCP-specific wiring the app needs. The agent gets the Marrow tools through the SDK, and the key is sent as a request header.

Step 3: Create the agent

The main agent lives in src/index.ts. It imports the OpenAI Agents SDK and combines Marrow MCP with a few local tools:

import { Agent, hostedMcpTool, isOpenAIResponsesRawModelStreamEvent, run } from '@openai/agents';

import { systemPrompt } from './prompts/system.prompt.ts';
import { duckdbTools } from './tools/duckdb.tools.ts';
import { fetchTools } from './tools/fetch.tools.ts';
import { outputTools } from './tools/output.tools.ts';
import { sleepTools } from './tools/sleep.tools.ts';

The agent itself is small:

const agent = new Agent({
    name: 'Data Analyst',
    instructions: systemPrompt,
    tools: [
        hostedMcpTool({
            serverLabel: 'marrow',
            serverUrl: 'https://mcp.marrow.com/mcp/v1',
            headers: {
                'marrow-mcp-key': process.env.MARROW_MCP_KEY ?? ''
            }
        }),
        ...sleepTools,
        ...fetchTools,
        ...duckdbTools,
        ...outputTools
    ],
    model: 'gpt-5.4-mini',
    modelSettings: {
        reasoning: {
            effort: 'high'
        }
    }
});

The important parts are:

hostedMcpTool(...) exposes Marrow tools to the agent
fetchTools, duckdbTools and outputTools handle the local workflow
systemPrompt tells the model what to do and what not to do
run(...) executes the agent and streams its output

Step 4: Understand the helper tools

The local tools make the sample app work like a real workflow, rather than a single prompt.

Download tool

src/tools/fetch.tools.ts adds download_file_from_url. Marrow export URLs are temporary, so the agent should fetch them right away and save them locally.

tool({
    name: 'download_file_from_url',
    description:
        'URGENT: Export links expire quickly, call this tool IMMEDIATELY before doing anything else. It downloads the file and returns the local file path.'
});

This keeps the workflow stable. The model can request an export URL from Marrow MCP, then pass it to the download tool before the link expires.

DuckDB tools

src/tools/duckdb.tools.ts is where the downloaded data becomes queryable:

tool({
    name: 'load_csv',
    description: 'Loads a CSV file from the local file system into a DuckDB table.'
});

The file also includes:

load_json for JSON or newline-delimited JSON files
list_tables to inspect what is loaded
run_sql_query to run standard SQL against DuckDB

This combination is the core of the tutorial. Marrow MCP supplies the export, and DuckDB lets the agent rank ASINs and inspect the data locally.

Final output tool

src/tools/output.tools.ts defines output_improved_listings. This tool is the app’s final step:

tool({
    name: 'output_improved_listings',
    description: 'Emits the final structured JSON for all improved ASIN listings.'
});

The agent should not write JSON directly in its response. Instead, it calls this tool once with all improved listings. The tool then writes the result to response/improved-listings-<timestamp>.json.

Step 5: Use the system prompt to guide the agent

The prompt in src/prompts/system.prompt.ts keeps the agent focused. It tells the model to:

use Marrow MCP tools when it needs export data
prefer SQL-based analysis through DuckDB
keep marketplace-specific content in the right language
never write JSON output directly in the chat

In practice, the agent behaves like a focused analyst rather than a generic chatbot.

Step 6: Run the app

Start the sample with:

yarn start

The app runs src/index.ts, streams the agent’s reasoning to the terminal and finishes by writing a JSON file to ./response/. Typical flow:

The agent asks Marrow MCP for the needed export.
The export URL is downloaded immediately.
DuckDB loads the file and the agent runs SQL to find weak ASINs.
The model rewrites the listing copy.
output_improved_listings saves the final result.

The output file contains one item per ASIN, with the current title and bullets alongside the improved version. That makes it easy to feed into another script, a bulk edit sheet, or a later workflow.

Use a simple mental model

If you want to adapt this pattern for another Marrow-powered agent, keep the same split:

Marrow MCP for source data
local tools for downloading, transforming, and validating
one dedicated output tool for the final artifact

This structure keeps the sample easy to extend without turning the agent into a pile of prompt instructions.

Marrow MCP resources

Check the following resources for more information:

MCP server URL: https://mcp.marrow.com/mcp/v1
Interactive Data Scheme
Data Scheme JSON: https://api.marrow.com/api/v1/spec/data-scheme
Need help? Use the contact form

Get Started

Plugins

Trust & Safety

Hologrow Marrow MCP

Use OpenAI Agents SDK with Marrow MCP

Use OpenAI Agents SDK with Marrow MCP

What you will build

Prerequisites

Step 1: Clone and install the repository

Step 2: Configure your keys

Step 3: Create the agent

Step 4: Understand the helper tools

Download tool

DuckDB tools

Final output tool

Step 5: Use the system prompt to guide the agent

Step 6: Run the app

Use a simple mental model

Marrow MCP resources

​Use OpenAI Agents SDK with Marrow MCP

​What you will build

​Prerequisites

​Step 1: Clone and install the repository

​Step 2: Configure your keys

​Step 3: Create the agent

​Step 4: Understand the helper tools

​Download tool

​DuckDB tools

​Final output tool

​Step 5: Use the system prompt to guide the agent

​Step 6: Run the app

​Use a simple mental model

​Related resources

​Marrow MCP resources

Use OpenAI Agents SDK with Marrow MCP

What you will build

Prerequisites

Step 1: Clone and install the repository

Step 2: Configure your keys

Step 3: Create the agent

Step 4: Understand the helper tools

Download tool

DuckDB tools

Final output tool

Step 5: Use the system prompt to guide the agent

Step 6: Run the app

Use a simple mental model

Related resources

Marrow MCP resources