Skip to main content

Building agents with Meltwater MCP

This guide is for developers building their own AI agents in code. It shows how to give an agent access to Meltwater MCP in the most common agent frameworks. For an introduction to what Meltwater MCP is and when to use it, see the Overview.

Connecting Meltwater in Claude, ChatGPT or another app?

If you want to add Meltwater to an AI assistant or code editor rather than write code, you don't need this guide. See Connectors for step-by-step setup for Claude, ChatGPT, Microsoft Copilot, Gemini, Cursor, VS Code and more.

Before you start​

You will need:

  • A Meltwater API token - see API Credentials if you need to create one.
  • An API key for the model provider your agent uses.
  • Python 3.10 or later for the examples below.

Authentication​

Every example connects to the Meltwater MCP server at https://api.meltwater.com/v2/mcp and sends your Meltwater API token in an apikey request header:

apikey: <YOUR MELTWATER API KEY>

Treat your API token like a password - do not embed it in client-side code or commit it to source control. The examples read it from a MELTWATER_API_KEY environment variable.

For the full connection details, including OAuth sign-in for clients that can open a browser, see Connectors.

OpenAI Responses API​

The OpenAI Responses API connects to remote MCP servers directly. Point it at the Meltwater MCP endpoint and pass your API token in the apikey header:

import os

from openai import OpenAI

client = OpenAI() # reads OPENAI_API_KEY

resp = client.responses.create(
model="gpt-4.1",
tools=[
{
"type": "mcp",
"server_label": "meltwater-mcp",
"server_url": "https://api.meltwater.com/v2/mcp",
"require_approval": "never",
"headers": {
"apikey": os.environ["MELTWATER_API_KEY"]
}
},
],
input="Summarise coverage of my brand over the last 7 days.",
)

print(resp.output_text)

OpenAI's servers make the MCP calls, so the model discovers the Meltwater tools and calls them as needed within a single request.

OpenAI Agents SDK​

The OpenAI Agents SDK connects to remote MCP servers over Streamable HTTP. Install it with pip install openai-agents.

import asyncio
import os

from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp


async def main():
async with MCPServerStreamableHttp(
name="Meltwater MCP",
params={
"url": "https://api.meltwater.com/v2/mcp",
"headers": {"apikey": os.environ["MELTWATER_API_KEY"]},
},
) as meltwater:
agent = Agent(
name="Media analyst",
instructions="Use the Meltwater tools to answer questions about media coverage. Cite sources and dates.",
mcp_servers=[meltwater],
)
result = await Runner.run(agent, "Summarise coverage of my brand over the last 7 days.")
print(result.final_output)


asyncio.run(main())

Here the MCP connection runs in your own process, so you can add more tools, hand-offs and guardrails alongside Meltwater.

Anthropic SDK (Claude)​

With the Anthropic SDK, connect to Meltwater MCP with the MCP Python SDK, then pass the tools to Claude through the SDK's tool runner, which calls them for you. Install both with pip install "anthropic[mcp]".

streamable_http_client returns the read and write streams. MCP Python SDK 1.x also returns a session-id callback as a third value, and that release still installs on Python 3.10. SDK 2.x returns only the two streams and requires Python 3.11 or later. The example keeps the first two values either way.

import asyncio
import os

from anthropic import AsyncAnthropic
from anthropic.lib.tools.mcp import async_mcp_tool
from mcp import ClientSession
from mcp.client.streamable_http import create_mcp_http_client, streamable_http_client


async def main():
http_client = create_mcp_http_client(headers={"apikey": os.environ["MELTWATER_API_KEY"]})

async with http_client, streamable_http_client(
"https://api.meltwater.com/v2/mcp", http_client=http_client
) as streams:
read, write, *_ = streams
async with ClientSession(read, write) as mcp_client:
await mcp_client.initialize()
tools = (await mcp_client.list_tools()).tools

client = AsyncAnthropic() # reads ANTHROPIC_API_KEY
runner = client.beta.messages.tool_runner(
model="claude-opus-5-5",
max_tokens=16000,
tools=[async_mcp_tool(tool, mcp_client) for tool in tools],
messages=[{"role": "user", "content": "Summarise coverage of my brand over the last 7 days."}],
)
final = await runner.until_done()
print("".join(block.text for block in final.content if block.type == "text"))


asyncio.run(main())
Why not the Messages API MCP connector?

The Claude Messages API also has a built-in MCP connector (the mcp_servers parameter), but it authenticates with an OAuth bearer token rather than a custom header. To use a Meltwater API token, connect from your own code as shown above.

Other frameworks​

Any framework that can connect to a remote MCP server over Streamable HTTP and send a custom header will work, following the same pattern as the examples above. For field-by-field values, see Any MCP client. To work with the protocol directly, see REST API.

Working with the tools​

Once connected, your agent lists the available tools through the standard MCP tool-discovery mechanism. The exact set of tools depends on the products in your Meltwater package - use the Tools Explorer to browse them before you write any code.

Tool descriptions matter

Each tool ships with a description that tells the LLM what it does and when to use it. These descriptions are critical to how well an agent selects and calls the right tool - review the tool list your agent discovers so you understand what it has access to, and keep your own instructions consistent with it.

For complete agents built on Meltwater MCP, see the Examples.

Getting help​

If you have any questions, take a look at the FAQs page. If you need further help, please reach out to our Support team.