OpenAI Responses API with Trends MCP

What happens when you attach Trends MCP

OpenAI's Responses API accepts a tool entry with "type": "mcp". On the first request, the runtime opens an HTTPS session to the remote server, runs the MCP tools/list handshake, and injects the returned schemas into the model context. When the model decides it needs external data, the API emits an mcp_call output item, executes the remote tool, and feeds the JSON result back into the same response chain.

Trends MCP exposes three keyword tools and fifteen live feeds behind one URL: https://api.trendsmcp.ai/mcp. The server speaks streamable HTTP transport, which matches what OpenAI documents for remote MCP. Authentication is a Bearer API key, the same credential used for POST https://api.trendsmcp.ai/api.

A snapshot from June 11, 2026 illustrates the shape of live output. A get_top_trends call with type: "Google Trends" and limit: 5 returned ranked queries including "karmelo anthony", "james handy", and "doodle for google" with as_of_ts: "2026-06-11T13:01:30.577009+00:00". A get_growth call on "artificial intelligence" across news volume and news sentiment for 3M showed news volume up 40.06% while sentiment rose 5.93% on the normalized 0 to 100 scale. Those numbers land in the model as structured JSON, ready for citation in the final answer.

Minimal tools block

The smallest working configuration names the server, points at Trends MCP, passes Bearer auth, and skips per-call approval prompts because all three tools are read-only.

{
  "type": "mcp",
  "server_label": "trends-mcp",
  "server_description": "Live trend time series, growth metrics, and platform leaderboards across Google, TikTok, YouTube, Reddit, Amazon, npm, Steam, and news signals.",
  "server_url": "https://api.trendsmcp.ai/mcp",
  "authorization": "Bearer YOUR_TRENDSMCP_API_KEY",
  "require_approval": "never"
}

Replace YOUR_TRENDSMCP_API_KEY with the key from https://www.trendsmcp.ai/account. OpenAI does not persist the authorization value. Send it on every responses.create call or tool discovery fails with 401 on the remote server.

Python example

Install openai and set OPENAI_API_KEY plus a Trends MCP key. The script below asks for cross-platform growth on the keyword mcp server, which is a common developer search phrase.

import os
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-4.1",
    tools=[
        {
            "type": "mcp",
            "server_label": "trends-mcp",
            "server_description": "Live normalized trend data across search, social, commerce, and developer platforms.",
            "server_url": "https://api.trendsmcp.ai/mcp",
            "authorization": f"Bearer {os.environ['TRENDSMCP_API_KEY']}",
            "require_approval": "never",
            "allowed_tools": ["get_growth", "get_trends", "get_top_trends"],
        }
    ],
    input=(
        "Using Trends MCP, compare 3M and YTD growth for the keyword "
        "'mcp server' on google search and npm. Cite the numeric growth "
        "percentages and dates from the tool response."
    ),
)

print(response.output_text)

Inspect response.output for trace items. Expect an mcp_list_tools item on the first turn, then one or more mcp_call items showing the exact JSON Trends MCP returned. Those calls are the audit trail for grounded answers.

curl example

The same configuration works from the shell when OPENAI_API_KEY and TRENDSMCP_API_KEY are exported.

curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-4.1",
    "tools": [
      {
        "type": "mcp",
        "server_label": "trends-mcp",
        "server_url": "https://api.trendsmcp.ai/mcp",
        "authorization": "Bearer '"$TRENDSMCP_API_KEY"'",
        "require_approval": "never",
        "allowed_tools": ["get_top_trends"]
      }
    ],
    "input": "Via Trends MCP, list the top 5 Google Trends searches right now."
  }'

Restricting allowed_tools to get_top_trends keeps the model from issuing broader keyword pulls when the user only asked for a live leaderboard.

JavaScript example

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-4.1",
  tools: [
    {
      type: "mcp",
      server_label: "trends-mcp",
      server_url: "https://api.trendsmcp.ai/mcp",
      authorization: `Bearer ${process.env.TRENDSMCP_API_KEY}`,
      require_approval: "never",
      allowed_tools: ["get_trends", "get_growth"],
    },
  ],
  input:
    "Using Trends MCP, show weekly Google Search history for 'langchain' over the last five years and quote the most recent data point.",
});

console.log(response.output_text);

Tool parameters the model must get right

Grounded pulls fail when parameter names drift. Trends MCP keyword sources use lowercase strings with spaces, such as google search, news volume, and npm. Live feeds use a separate type field with case-sensitive labels. The MCP tool is get_top_trends, and the feed argument is type, not source.

For get_growth, preset strings include 7D, 30D, 3M, 6M, 12M, YTD, MTD, and QTD. Custom windows use objects with recent and baseline dates in YYYY-MM-DD format. A June 2026 pull on mcp server with baseline 2026-03-01 and recent 2026-06-01 returned +12.12% on Google Search while the rolling 3M preset on the same keyword showed -52.56%, which shows why launch-specific windows matter for product analytics.

Multi-source growth accepts comma-separated sources in one call, for example source: "google search, npm". The response lists each source separately with its own recent_date, baseline_date, and growth fields.

Prompt patterns that route correctly

Models follow explicit routing language. These templates match the examples in Trends MCP documentation:

1. "Using Trends MCP, show Google Search trend history for nvidia weekly."
2. "Via Trends MCP, what is the 3M and YTD growth for ozempic on google search and tiktok?"
3. "Using Trends MCP, what are the top 10 TikTok Trending Hashtags today?"

The phrases "Using Trends MCP" or "Via Trends MCP" reduce accidental web search when both MCP and browsing tools are enabled.

Responses API trace items to log

Production agents should store three output types from each turn.

mcp_list_tools lists every tool name and JSON schema Trends MCP exported. Use it to verify the remote catalog matches expectations after deploys.

mcp_call records the tool name, arguments the model chose, and the raw JSON payload returned. This is the evidence layer for compliance and debugging hallucinated percentages.

message items contain the natural-language answer. Compare cited numbers against the nearest mcp_call body before returning text to end users.

Request budget and looping

Trends MCP meters usage per successful tool invocation. On the free tier, 100 requests per month apply across REST and MCP.

An agent that calls get_growth with source: "all" still counts as one Trends MCP request, even though the JSON bundles many platforms. A loop that asks for ten keywords on ten sources without batching can burn the monthly quota in a single Responses API session. For heavy workloads, cache mcp_call JSON in your database and pass summaries on follow-up turns. The Python trends client uses the same API shape if you want deterministic pulls outside the model loop.

Errors you will see in practice

Where this fits in a larger stack

The Responses API path suits backend services, batch report generators, and agent prototypes that already use OpenAI's unified trace format. ChatGPT custom connectors suit analyst workflows inside the chat UI; see the ChatGPT setup page for that path. LangChain and LangGraph teams often wrap the same endpoint through adapter libraries described on the LangChain integration page. All three patterns hit identical trend JSON underneath.

For agents that only need deterministic extracts, POST https://api.trendsmcp.ai/api with the same Bearer token skips MCP discovery entirely. Mixed designs are common: scheduled REST jobs write trend snapshots to a warehouse, while the Responses API layer handles ad hoc analyst questions against live data.