Skip to main content

Connecting a custom agent to Meltwater MCP

This guide is for developers building their own AI agents. We'll show you how to connect a custom agent or MCP client to the Meltwater MCP server in code. For an introduction to what Meltwater MCP is and when to use it, see the Overview.

Looking to connect Meltwater in Claude or ChatGPT?

If you're not building your own agent and just want to add Meltwater as a tool source inside the Claude or ChatGPT apps, you don't need this guide. Meltwater provides no-code connectors for both - see the Meltwater community site for step-by-step instructions.

Before you start​

To connect to Meltwater MCP you will need:

  • A Meltwater API token - see API Credentials if you need to create one.
  • An MCP-compatible client or agent (for example the OpenAI Agents SDK, the Anthropic SDK, or your own framework).

The MCP endpoint​

Meltwater MCP is served from a single endpoint:

https://api.meltwater.com/v2/mcp

Point your MCP client at this URL and it will discover the available tools automatically.

Authentication​

Meltwater MCP is authenticated with your Meltwater API token, sent as an apikey request header:

apikey: <YOUR MELTWATER API KEY>
OAuth coming later this year

API token authentication is the only supported method today. Support for OAuth 2.0 is planned for later this year, which will make it easier to connect Meltwater MCP without distributing long-lived tokens. This guide will be updated when OAuth is available.

Treat your API token like a password - do not embed it in client-side code or commit it to source control. Use environment variables or a secrets manager instead.

Connecting with the OpenAI Responses API​

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

from openai import OpenAI

client = OpenAI(api_key="<YOUR 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": "<YOUR MELTWATER API KEY>"
            }
        },
    ],
    input="Summarise coverage of my brand over the last 7 days.",
)

print(resp.output_text)

The model will discover the tools Meltwater MCP exposes and call them as needed to answer the prompt.

Discovering the available tools​

Once connected, your client can list the available tools through the standard MCP tool-discovery mechanism. Broadly, the tools fall into two groups:

  • Your assets - tools that let an agent find and work with objects you have set up in Meltwater, such as saved searches and tags.
  • Meltwater data - tools that retrieve mentions, analytics, and insights from the Meltwater platform.

The exact set of tools available to you depends on the products in your Meltwater package.

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 - if you are building a custom agent, review the tool list your client discovers so you understand what your agent has access to.

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.