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.
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())
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.
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.