SIGN UPLOG IN
X (Twitter)LinkedInGitHubDiscordYouTube

How to integrate Semrush MCP with Vercel AI SDK v6

Connect Vercel AI SDK v6 to Semrush MCP. Show top anchor texts for example.com, compare backlink profiles for three domains, and more using natural language, with authentication handled for you.

Get started for freeGet a demo
Semrush logoSemrush
Api Key

Semrush is a leading SEO tool suite for keyword research, competitor analysis, and campaign tracking. It empowers marketers to improve search rankings and optimize online visibility.

74 Tools

Introduction

This guide walks you through connecting Semrush to Vercel AI SDK v6 using the Composio tool router. By the end, you'll have a working Semrush agent that can research organic and paid keywords, analyze backlinks, compare competitor domains, track local map rankings, and manage business listings through natural language commands.

This guide will help you understand how to give your Vercel AI SDK agent real control over a Semrush account through Composio's Semrush MCP server.

Before we dive in, let's take a quick look at the key ideas and tools involved.

Also integrate Semrush with

Claude CodeCursorChatGPTClaude CoworkAntigravityOpenAI Agents SDKClaude Agent SDKMuseCodexKimi CodeGrok BuildVS CodeOpenCodeOpenClawHermesAtomic AgentCLIGoogle ADKLangChainMastra AILlamaIndexCrewAIPydantic AIAutoGen

TL;DR

Here's what you'll learn:
  • How to set up and configure a Vercel AI SDK agent with Semrush integration
  • Using Composio's Tool Router to dynamically load and access Semrush tools
  • Creating an MCP client connection using HTTP transport
  • Building an interactive CLI chat interface with conversation history management
  • Handling tool calls and results within the Vercel AI SDK framework

What is Vercel AI SDK?

The Vercel AI SDK is a TypeScript library for building AI-powered applications. It provides tools for creating agents that can use external services and maintain conversation state.

Key features include:

  • streamText: Core function for streaming responses with real-time tool support
  • MCP Client: Built-in support for Model Context Protocol via @ai-sdk/mcp
  • Step Counting: Control multi-step tool execution with stopWhen: stepCountIs()
  • OpenAI Provider: Native integration with OpenAI models

What is the Semrush MCP server, and what's possible with it?

The Semrush MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your Semrush account. It provides structured and secure access to keyword, search competitor, backlink, and advertising data, so your agent can research keywords, compare domains, inspect backlink profiles, analyze search competitors, and review paid campaigns on your behalf.

  • Keyword research and content planning: Have your agent find related, broad match, and question-based keywords, then review search volume, cost per click, competition, and keyword difficulty.
  • Organic search analysis: Let the agent examine a domain's ranking keywords, top organic pages, ranking subdomains, and search results across supported regional databases.
  • Competitor and keyword gap research: Direct your agent to identify organic or paid search competitors and compare up to five domains for shared, unique, and missing keywords.
  • Backlink profile assessment: Instruct your agent to review backlinks, referring domains, anchor text, indexed pages, authority score distribution, historical trends, and geographic or top-level domain diversity.
  • Paid search and shopping research: Have your agent inspect paid keywords, search ads, advertising history, Product Listing Ad keywords and copies, and competing advertisers.

What is the Composio tool router, and how does it fit here?

What is Composio SDK?

Composio's Composio SDK helps agents find the right tools for a task at runtime. You can plug in multiple toolkits (like Gmail, HubSpot, and GitHub), and the agent will identify the relevant app and action to complete multi-step workflows. This can reduce token usage and improve the reliability of tool calls. Read more here: Getting started with Composio SDK

The tool router generates a secure MCP URL that your agents can access to perform actions.

How the Composio SDK works

The Composio SDK follows a three-phase workflow:

  1. Discovery: Searches for tools matching your task and returns relevant toolkits with their details.
  2. Authentication: Checks for active connections. If missing, creates an auth config and returns a connection URL via Auth Link.
  3. Execution: Executes the action using the authenticated connection.

Step-by-step Guide

Step by step09 STEPS
1

Prerequisites

Before you begin, make sure you have:
  • Node.js and npm installed
  • A Composio account with API key
  • An OpenAI API key
2

Getting API Keys for OpenAI and Composio

OpenAI API Key
  • Go to the OpenAI dashboard and create an API key. You'll need credits to use the models, or you can connect to another model provider.
  • Keep the API key safe.
Composio API Key
  • Log in to the Composio dashboard.
  • Navigate to your API settings and generate a new API key.
  • Store this key securely as you'll need it for authentication.
3

Install required dependencies

bash
npm install @ai-sdk/openai @ai-sdk/mcp @composio/core ai dotenv

First, install the necessary packages for your project.

What you're installing:

  • @ai-sdk/openai: Vercel AI SDK's OpenAI provider
  • @ai-sdk/mcp: MCP client for Vercel AI SDK
  • @composio/core: Composio SDK for tool integration
  • ai: Core Vercel AI SDK
  • dotenv: Environment variable management
4

Set up environment variables

bash
OPENAI_API_KEY=your_openai_api_key_here
COMPOSIO_API_KEY=your_composio_api_key_here
COMPOSIO_USER_ID=your_user_id_here

Create a .env file in your project root.

What's needed:

  • OPENAI_API_KEY: Your OpenAI API key for GPT model access
  • COMPOSIO_API_KEY: Your Composio API key for tool access
  • COMPOSIO_USER_ID: A unique identifier for the user session
5

Import required modules and validate environment

typescript
import "dotenv/config";
import { openai } from "@ai-sdk/openai";
import { Composio } from "@composio/core";
import * as readline from "readline";
import { streamText, type ModelMessage, stepCountIs } from "ai";
import { createMCPClient } from "@ai-sdk/mcp";

const composioAPIKey = process.env.COMPOSIO_API_KEY;
const composioUserID = process.env.COMPOSIO_USER_ID;

if (!process.env.OPENAI_API_KEY) throw new Error("OPENAI_API_KEY is not set");
if (!composioAPIKey) throw new Error("COMPOSIO_API_KEY is not set");
if (!composioUserID) throw new Error("COMPOSIO_USER_ID is not set");

const composio = new Composio({
  apiKey: composioAPIKey,
});
What's happening:
  • We're importing all necessary libraries including Vercel AI SDK's OpenAI provider and Composio
  • The dotenv/config import automatically loads environment variables
  • The MCP client import enables connection to Composio's tool server
6

Create Tool Router session and initialize MCP client

typescript
async function main() {
  // Create a tool router session for the user
  const session = await composio.create(composioUserID!, {
    toolkits: ["semrush"],
  });

  const mcpUrl = session.mcp.url;
What's happening:
  • We're creating a Tool Router session that gives your agent access to Semrush tools
  • The create method takes the user ID and specifies which toolkits should be available
  • The returned mcp object contains the URL and authentication headers needed to connect to the MCP server
  • This session provides access to all Semrush-related tools through the MCP protocol
7

Connect to MCP server and retrieve tools

typescript
const mcpClient = await createMCPClient({
  transport: {
    type: "http",
    url: mcpUrl,
    headers: session.mcp.headers, // Authentication headers for the Composio MCP server
  },
});

const tools = await mcpClient.tools();
What's happening:
  • We're creating an MCP client that connects to our Composio Tool Router session via HTTP
  • The mcp.url provides the endpoint, and mcp.headers contains authentication credentials
  • The type: "http" is important - Composio requires HTTP transport
  • tools() retrieves all available Semrush tools that the agent can use
8

Initialize conversation and CLI interface

typescript
let messages: ModelMessage[] = [];

console.log("Chat started! Type 'exit' or 'quit' to end the conversation.\n");
console.log(
  "Ask any questions related to semrush, like summarize my last 5 emails, send an email, etc... :)))\n",
);

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout,
  prompt: "> ",
});

rl.prompt();
What's happening:
  • We initialize an empty messages array to maintain conversation history
  • A readline interface is created to accept user input from the command line
  • Instructions are displayed to guide the user on how to interact with the agent
9

Handle user input and stream responses with real-time tool feedback

typescript
rl.on("line", async (userInput: string) => {
  const trimmedInput = userInput.trim();

  if (["exit", "quit", "bye"].includes(trimmedInput.toLowerCase())) {
    console.log("\nGoodbye!");
    rl.close();
    process.exit(0);
  }

  if (!trimmedInput) {
    rl.prompt();
    return;
  }

  messages.push({ role: "user", content: trimmedInput });
  console.log("\nAgent is thinking...\n");

  try {
    const stream = streamText({
      model: openai("gpt-5"),
      messages,
      tools,
      toolChoice: "auto",
      stopWhen: stepCountIs(10),
      onStepFinish: (step) => {
        for (const toolCall of step.toolCalls) {
          console.log(`[Using tool: ${toolCall.toolName}]`);
          }
          if (step.toolCalls.length > 0) {
            console.log(""); // Add space after tool calls
          }
        },
      });

      for await (const chunk of stream.textStream) {
        process.stdout.write(chunk);
      }

      console.log("\n\n---\n");

      // Get final result for message history
      const response = await stream.response;
      if (response?.messages?.length) {
        messages.push(...response.messages);
      }
    } catch (error) {
      console.error("\nAn error occurred while talking to the agent:");
      console.error(error);
      console.log(
        "\nYou can try again or restart the app if it keeps happening.\n",
      );
    } finally {
      rl.prompt();
    }
  });

  rl.on("close", async () => {
    await mcpClient.close();
    console.log("\n👋 Session ended.");
    process.exit(0);
  });
}

main().catch((err) => {
  console.error("Fatal error:", err);
  process.exit(1);
});
What's happening:
  • We use streamText instead of generateText to stream responses in real-time
  • toolChoice: "auto" allows the model to decide when to use Semrush tools
  • stopWhen: stepCountIs(10) allows up to 10 steps for complex multi-tool operations
  • onStepFinish callback displays which tools are being used in real-time
  • We iterate through the text stream to create a typewriter effect as the agent responds
  • The complete response is added to conversation history to maintain context
  • Errors are caught and displayed with helpful retry suggestions

Complete Code

Here's the complete code to get you started with Semrush and Vercel AI SDK:

typescript
import "dotenv/config";
import { openai } from "@ai-sdk/openai";
import { Composio } from "@composio/core";
import * as readline from "readline";
import { streamText, type ModelMessage, stepCountIs } from "ai";
import { createMCPClient } from "@ai-sdk/mcp";

const composioAPIKey = process.env.COMPOSIO_API_KEY;
const composioUserID = process.env.COMPOSIO_USER_ID;

if (!process.env.OPENAI_API_KEY) throw new Error("OPENAI_API_KEY is not set");
if (!composioAPIKey) throw new Error("COMPOSIO_API_KEY is not set");
if (!composioUserID) throw new Error("COMPOSIO_USER_ID is not set");

const composio = new Composio({
  apiKey: composioAPIKey,
});

async function main() {
  // Create a tool router session for the user
  const session = await composio.create(composioUserID!, {
    toolkits: ["semrush"],
  });

  const mcpUrl = session.mcp.url;

  const mcpClient = await createMCPClient({
    transport: {
      type: "http",
      url: mcpUrl,
      headers: session.mcp.headers, // Authentication headers for the Composio MCP server
    },
  });

  const tools = await mcpClient.tools();

  let messages: ModelMessage[] = [];

  console.log("Chat started! Type 'exit' or 'quit' to end the conversation.\n");
  console.log(
    "Ask any questions related to semrush, like summarize my last 5 emails, send an email, etc... :)))\n",
  );

  const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout,
    prompt: "> ",
  });

  rl.prompt();

  rl.on("line", async (userInput: string) => {
    const trimmedInput = userInput.trim();

    if (["exit", "quit", "bye"].includes(trimmedInput.toLowerCase())) {
      console.log("\nGoodbye!");
      rl.close();
      process.exit(0);
    }

    if (!trimmedInput) {
      rl.prompt();
      return;
    }

    messages.push({ role: "user", content: trimmedInput });
    console.log("\nAgent is thinking...\n");

    try {
      const stream = streamText({
        model: openai("gpt-5"),
        messages,
        tools,
        toolChoice: "auto",
        stopWhen: stepCountIs(10),
        onStepFinish: (step) => {
          for (const toolCall of step.toolCalls) {
            console.log(`[Using tool: ${toolCall.toolName}]`);
          }
          if (step.toolCalls.length > 0) {
            console.log(""); // Add space after tool calls
          }
        },
      });

      for await (const chunk of stream.textStream) {
        process.stdout.write(chunk);
      }

      console.log("\n\n---\n");

      // Get final result for message history
      const response = await stream.response;
      if (response?.messages?.length) {
        messages.push(...response.messages);
      }
    } catch (error) {
      console.error("\nAn error occurred while talking to the agent:");
      console.error(error);
      console.log(
        "\nYou can try again or restart the app if it keeps happening.\n",
      );
    } finally {
      rl.prompt();
    }
  });

  rl.on("close", async () => {
    await mcpClient.close();
    console.log("\n👋 Session ended.");
    process.exit(0);
  });
}

main().catch((err) => {
  console.error("Fatal error:", err);
  process.exit(1);
});

Conclusion

You've successfully built a Semrush agent using the Vercel AI SDK with streaming capabilities! This implementation provides a powerful foundation for building AI applications with natural language interfaces and real-time feedback.

Key features of this implementation:

  • Real-time streaming responses for a better user experience with typewriter effect
  • Live tool execution feedback showing which tools are being used as the agent works
  • Dynamic tool loading through Composio's Tool Router with secure authentication
  • Multi-step tool execution with configurable step limits (up to 10 steps)
  • Comprehensive error handling for robust agent execution
  • Conversation history maintenance for context-aware responses

You can extend this further by adding custom error handling, implementing specific business logic, or integrating additional Composio toolkits to create multi-app workflows.
TOOLS

Supported Tools

Every Semrush action and event your agent gets out of the box.

Check Semrush account units balance

Fetch remaining Semrush Standard API units for a legacy v3 connection.

Add Semrush review comment

Publish an owner comment to a review that supports replies.

Get ad copies

Retrieves unique ad copies Semrush has observed for a specified domain from a regional database, detailing ads seen in Google's paid search results.

Get competitors in organic search

Use to get a domain's organic search competitors from Semrush as a semicolon-separated string; `display_date` requires 'YYYYMM15' format if used.

Get competitors in paid search

Retrieves a list of a domain's competitors in paid search results from a specified regional database.

Create Semrush GBP post

Create a draft, scheduled, or ready-to-send GBP post.

Create Listing Management location

Create a Semrush Listing Management location.

Create location image

Add a base64-encoded JPEG or PNG image to a Semrush Listing Management location using a read-write v4 key and Local Pro or Business.

Manage Semrush GBP suggestion

Start accepting or rejecting an open GBP suggestion.

Delete Semrush GBP post

Permanently delete a DRAFT, SCHEDULED, or TO_SEND GBP post.

Delete Listing Management location

Permanently delete an eligible location using a read-write v4 key and Local plan.

Delete location image

Permanently delete an image using a read-write v4 key and Local plan.

Delete Semrush review comment

Permanently remove a public review comment.

Disable location listing

Stop distribution for a controllable listing; a parent may affect child listings.

Get domain ad history

Retrieves a domain's 12-month advertising history from Semrush (keywords bid on, ad positions, ad copy) for PPC strategy and competitor analysis; most effective when the domain has ad history in the selected database.

Get domain organic pages

Fetches a report on a domain's unique organic pages ranking in Google's top 100 search results, with options for specifying database, date, columns, sorting, and filtering.

Get domain organic search keywords

Retrieves an organic search keyword report for a domain from a selected Semrush regional database.

Get domain organic subdomains

Retrieves a report on subdomains of a given domain that rank in Google's top 100 organic search results for a specified regional database.

Get domain paid search keywords

Fetches keywords driving paid search traffic to a specified, existing domain using a supported Semrush regional database.

Get PLA search keywords for a domain

Retrieves Product Listing Ad (PLA) search keywords for a specified domain from a Semrush regional database.

Compare domains

Analyzes keyword rankings by comparing up to five domains to find common, unique, or gap keywords, using specified organic/paid types and comparison logic in the `domains` string.

Enable location listing

Resume distribution for a controllable disconnected listing.

Get Semrush GBP metrics

Return GBP metrics for up to five locations.

Get Listing Management location

Get one Listing Management location using a v4 key and Local Pro or Business.

Get Semrush review auto-reply config

Return review auto-reply settings for a location.

Get Semrush review overview

Return review counts, rating distribution, and reply statistics.

List Semrush GBP additional-hour types

Return additional business-hour types available for a GBP location.

List Semrush GBP attributes

Return GBP attributes and allowed values for a category and country.

List Semrush GBP categories

Return GBP categories supported in a country.

List Semrush GBP posts

Return filtered GBP posts for one or more Semrush locations.

List Semrush GBP suggestions

Return GBP data-change suggestions for one or more active locations.

List Listing Management locations

List locations using a v4 key and Local Pro or Business; uses no API units.

List location categories

List Semrush Local business categories supported for a country.

List location images

List location images using a v4 key and Local Pro or Business.

List location listings

Get directory listings using a v4 key and Local Pro or Business.

List location payment options

Get payment options using a v4 key and Local Pro or Business.

List Semrush location reviews

Return a filtered, paginated list of reviews for a Semrush location.

Collect Map Rank Tracker campaign data (consumes credits)

Start a data-collection mutation that creates a new campaign report.

Create Map Rank Tracker campaign

Create persistent Map Rank Tracker campaign data.

Delete Map Rank Tracker campaign

Permanently delete a campaign and all its collected data.

Get Map Rank Tracker campaign

Get one Map Rank Tracker campaign without consuming API units.

Get Map Rank Tracker heatmap

Get a campaign heatmap for one keyword and report timestamp.

Get Map Rank Tracker keyword statuses

Get campaign keyword statuses for the latest or a specified report.

Get Map Rank Tracker metrics

Get average-position and share-of-voice history for one keyword.

Get Map Rank Tracker user limits

Get campaign-slot and monthly Map Rank Tracker credit limits.

List Map Rank Tracker campaigns

List and filter Map Rank Tracker campaigns without consuming API units.

List Map Rank Tracker top competitors

Get a paginated competitor ranking for one keyword and report.

Update Map Rank Tracker campaign

Mutate selected settings of an existing Map Rank Tracker campaign.

Get PLA competitors

Retrieves domains competing with a specified domain in Google's Product Listing Ads (PLA) from a given Semrush regional database.

Get PLA copies

Fetches Product Listing Ad (PLA) copies that Semrush observed for a domain in Google's paid search results.

Update Semrush GBP post

Update a DRAFT, SCHEDULED, or TO_SEND GBP post.

Update Listing Management location

Patch selected fields on a Semrush Listing Management location.

Update location image

Replace a location image caption using a read-write v4 key and Local Pro or Business.

Replace Semrush review auto-reply config

Replace all review auto-reply settings for a location.

Update Semrush review comment

Replace the public text of an editable review comment.

List v4 backlink anchors

List v4 backlink anchors for a URL or domain.

Get v4 authority score profile

Get the v4 referring-domain authority-score distribution.

List v4 backlink competitors

List v4 backlink competitors based on referring-domain overlap.

List v4 backlinks

List v4 backlinks with field selection, filtering, sorting, and pagination.

Compare v4 backlink summaries

Compare v4 backlink summaries for up to ten targets.

Get v4 backlinks historical summary

Get monthly v4 backlink history for a URL or domain.

Get v4 backlinks matrix

Compare shared referring domains and backlinks for up to six targets.

Get v4 backlinks overview

Get aggregated v4 backlink metrics for a URL or domain.

Create v4 project

Create a Semrush v4 project for a domain.

Delete v4 project

Permanently delete a Semrush v4 project and all associated data.

Get v4 project

Get the full details of one accessible Semrush v4 project.

List v4 indexed pages

List v4 indexed backlink pages for a URL or domain.

Get v4 keyword metrics

Get Semrush v4 SEO and PPC metrics for one keyword and country.

List v4 projects

List Semrush v4 projects by ownership or sharing scope.

List v4 referring domains

List v4 referring domains for a URL or domain.

List v4 referring IPs

List v4 referring IP addresses for a URL or domain.

Update v4 project

Rename a Semrush v4 project.

Validate Listing Management location creation

Validate a Listing Management location payload without creating it or consuming a Local Pro location limit.

Validate Listing Management location update

Validate selected changes to a Listing Management location without applying them.

FRAMEWORKS

How to build Semrush MCP Agent with another framework

Claude Code logo

Claude Code

Use Semrush MCP with Claude Code

Cursor logo

Cursor

Use Semrush MCP with Cursor

ChatGPT logo

ChatGPT

Use Semrush MCP with ChatGPT

Claude Cowork logo

Claude Cowork

Use Semrush MCP with Claude Cowork

Antigravity logo

Antigravity

Use Semrush MCP with Antigravity

OpenAI Agents SDK logo

OpenAI Agents SDK

Use Semrush MCP with OpenAI Agents SDK

Claude Agent SDK logo

Claude Agent SDK

Use Semrush MCP with Claude Agent SDK

Muse logo

Muse

Use Semrush MCP with Muse

Codex logo

Codex

Use Semrush MCP with Codex

Kimi Code logo

Kimi Code

Use Semrush MCP with Kimi Code

Grok Build logo

Grok Build

Use Semrush MCP with Grok Build

VS Code logo

VS Code

Use Semrush MCP with VS Code

OpenCode logo

OpenCode

Use Semrush MCP with OpenCode

OpenClaw logo

OpenClaw

Use Semrush MCP with OpenClaw

Hermes logo

Hermes

Use Semrush MCP with Hermes

Atomic Agent logo

Atomic Agent

Use Semrush MCP with Atomic Agent

CLI logo

CLI

Use Semrush MCP with CLI

Google ADK logo

Google ADK

Use Semrush MCP with Google ADK

LangChain logo

LangChain

Use Semrush MCP with LangChain

Mastra AI logo

Mastra AI

Use Semrush MCP with Mastra AI

LlamaIndex logo

LlamaIndex

Use Semrush MCP with LlamaIndex

CrewAI logo

CrewAI

Use Semrush MCP with CrewAI

Pydantic AI logo

Pydantic AI

Use Semrush MCP with Pydantic AI

AutoGen logo

AutoGen

Use Semrush MCP with AutoGen

FAQ

Frequently asked questions

With a standalone Semrush MCP server, the agents and LLMs can only access a fixed set of Semrush tools tied to that server. However, with the Composio Tool Router, agents can dynamically load tools from Semrush and many other apps based on the task at hand, all through a single MCP endpoint.

Yes, you can. Vercel AI SDK v6 fully supports MCP integration. You get structured tool calling, message history handling, and model orchestration while Tool Router takes care of discovering and serving the right Semrush tools.

Yes, absolutely. You can configure which Semrush scopes and actions are allowed when connecting your account to Composio. You can also bring your own OAuth credentials or API configuration so you keep full control over what the agent can do.

All sensitive data such as tokens, keys, and configuration is fully encrypted at rest and in transit. Composio is SOC 2 Type 2 compliant and follows strict security practices so your Semrush data and credentials are handled as safely as possible.

Start with Semrush.It takes 30 seconds.

Managed auth, hosted MCP servers, and every Semrush tool your agent needs.Free to start.

Start building