// VYDAI MCP server · documentation

MCP server documentation

Everything you need to connect VYDAI to an AI assistant and understand its answers: the full list of tools, setup for each assistant, limits and fixes for common problems.

Page contents

What it is and how it works

MCP (Model Context Protocol) is an open standard that lets an AI assistant use data from other services. VYDAI runs an MCP server at https://vydai.inweb.ua/mcp, and the assistant calls it when your question is about your brand’s AI visibility.

You ask in plain language, the assistant picks the VYDAI tools it needs, gets the data and writes the answer. A tool is a single request to VYDAI, such as “visibility for a period” or “list of prompts”.

Access works through a personal key you create in your workspace. For each key you choose all your projects or only some of them. The key only reads data: it changes nothing, runs no checks and does not spend your balance.

What you can ask

The server has 16 tools and 2 ready-made templates. You do not need to know the tool names: the assistant picks them itself. They are listed so you can see where an answer comes from.

What you can specify
  • Project. The assistant finds it through the project list, so naming the project or domain is enough.
  • Period. Start and end dates in Kyiv time, both inclusive. For visibility, competitor, source and traffic data, up to 92 days. You can say “for October” or “for the last two weeks”, and the assistant turns it into dates.
  • AI systems. You can limit an answer to specific systems: ChatGPT (openai), Gemini (gemini), Claude (claude), Google AI Overviews (google_aio), Google AI Mode (google_ai_mode).

Projects and prompts

ping

Checks the connection and shows how many projects the key can access.

Sample question: “Check whether the VYDAI connection works.”

What you can specify: Nothing.

list_projects

Projects available to the key: name, domain, region and status.

Sample question: “Show my VYDAI projects.”

What you can specify: Nothing.

get_project

Project settings: brand name variants, AI systems, check schedule, number of active prompts, up to 50 competitors and the date of the last check.

Sample question: “Which AI systems and competitors are set up for example.com?”

What you can specify: Project.

list_prompts

Project prompts, the questions VYDAI asks AI systems: text, category, systems and the date of the last check.

Sample question: “Show active prompts in the Pricing category.”

What you can specify: Project, category, active only or all (active only by default), up to 200 prompts.

Visibility and trends

get_visibility_summary

Key metrics for a period: brand visibility as a percentage, mentions and checks, a breakdown by AI system, the share of answers with Google AI Overviews and the change from the previous period of the same length.

Sample question: “What was our brand visibility in October and how did it change from September?”

What you can specify: Project, period, AI systems.

get_visibility_trend

Visibility by day or by week over a period, broken down by AI system.

Sample question: “How did visibility change week by week over the last three months?”

What you can specify: Project, period, AI systems, step: day or week (day by default).

get_prompt_breakdown

Visibility for each prompt: checks, mentions and systems. You can also get only the prompts that lost or gained a brand mention during the period.

Sample question: “Which prompts stopped mentioning us this month?”

What you can specify: Project, period, AI systems, category, sorting (lost, gained, lowest or highest visibility first), up to 100 prompts.

Competitors and sources

get_competitor_share

Visibility of your brand and competitors for a period, mention counts, a breakdown by AI system and the change from the previous period.

Sample question: “Which competitors grew over the last month?”

What you can specify: Project, period, AI systems.

get_top_sources

Domains AI systems cite most often: up to 10 top ones, plus up to 6 new and 6 lost sources, comparing the first and last days of the period that have check results.

Sample question: “Which sites does AI cite most often in our answers?”

What you can specify: Project, period, AI systems.

AI answers

get_prompt_answers

Recent AI answers to a specific prompt: date, system, model, answer text (up to 2,000 characters) and up to 15 sources.

Sample question: “What exactly did ChatGPT answer to the delivery prompt last week?”

What you can specify: Project and prompt. Optionally an AI system, a period and the number of answers from 1 to 5 (3 by default).

GEO audits and checks

list_geo_audits

Recent GEO audits of your site, up to 20. GEO (Generative Engine Optimization) means optimizing a site for AI answers.

Sample question: “Which GEO audits have we run?”

What you can specify: Project.

get_geo_audit

The result of one audit: overall score, category scores and up to 10 top issues, blockers first.

Sample question: “What did the latest GEO audit show and what should we fix first?”

What you can specify: Project, audit.

get_check_status

Status of the latest check and checks that failed in the last 7 days.

Sample question: “Did today’s check finish without errors?”

What you can specify: Project.

Traffic and balance

get_ai_traffic

Visits from AI sources and up to 10 top landing pages from Google Analytics 4. Works if GA4 is connected in the project settings.

Sample question: “How many visitors came from AI assistants this month?”

What you can specify: Project, period.

get_billing_summary

Balance, limits and usage of your account. Available only for a key with access to all projects.

Sample question: “How many limits are left this month?”

What you can specify: Nothing.

Public ratings

get_topic_leaderboard

Leaders of a VYDAI public topic rating and the date of the last update.

Sample question: “Which brands lead the consumer electronics stores rating?”

What you can specify: Topic: the part of the rating address between /rating/ and -ai-visibility; 1 to 20 brands (20 by default).

Ready-made templates

A template is a prepared task the assistant completes with several tools in a row. In assistants that support MCP templates, they appear as ready commands. In Claude Code you find them in the menu that opens with /.

monthly_visibility_report

A monthly visibility report: the headline, metric changes, trend, prompts that gained or lost a mention, competitive position and caveats.

What you can specify: Project and month in YYYY-MM format.

lost_mentions_review

A lost-mentions review: which prompts lost the brand, what AI systems answered, likely causes and next steps.

What you can specify: Project, start and end dates.

Setup

First create a key in your workspace under “AI assistants”. VYDAI shows a ready command or config snippet there with your key already filled in. Below are the same instructions with <your key> in place of the key.

Claude Code

One terminal command, the same on macOS and Windows.

Where the settings live

  • You do not need to edit any file: the command saves the Claude Code settings itself.
  • By default VYDAI is available in the folder where you ran the command. To make it work in every folder, add --scope user to the command.

How to connect

  1. Run in the terminal:
    Terminal
    claude mcp add --transport http vydai https://vydai.inweb.ua/mcp --header "Authorization: Bearer <your key>"

How to check

Run claude mcp list: vydai should be marked as connected. Then ask Claude Code: “Show my VYDAI projects”.

How to disconnect

Run the command. If you added the server with --scope user, add it here too.

Terminal
claude mcp remove vydai

Claude Desktop

Claude Desktop connects through a small helper program, mcp-remote, so Node.js must be installed on your computer. It is free from nodejs.org; choose the LTS version.

Where the settings live

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • The easiest way to open the file is from the app: Settings → Developer → Edit Config.

How to connect

  1. Paste the snippet into the file. If it already has an mcpServers section, add only the vydai block inside it.
    claude_desktop_config.json
    {
      "mcpServers": {
        "vydai": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://vydai.inweb.ua/mcp",
            "--header",
            "Authorization:${AUTH_HEADER}"
          ],
          "env": {
            "AUTH_HEADER": "Bearer <your key>"
          }
        }
      }
    }
  2. Quit Claude Desktop completely (Cmd+Q on macOS, the system tray icon on Windows) and open it again.

How to check

In a new chat, ask: “Show my VYDAI projects”. VYDAI tools also appear in the tools menu below the message box.

How to disconnect

Delete the vydai block from the config file and restart the app.

Cursor

Cursor connects directly, with no extra programs.

Where the settings live

  • macOS: ~/.cursor/mcp.json
  • Windows: %USERPROFILE%\.cursor\mcp.json
  • A .cursor/mcp.json file inside a project also works, but it is better not to put the key there: such a file is easy to commit to a repository by accident.

How to connect

  1. Paste the snippet into the file. If it already has an mcpServers section, add only the vydai block inside it.
    mcp.json
    {
      "mcpServers": {
        "vydai": {
          "url": "https://vydai.inweb.ua/mcp",
          "headers": {
            "Authorization": "Bearer <your key>"
          }
        }
      }
    }
  2. Save the file. If VYDAI does not appear in the MCP section of Cursor settings, restart Cursor.

How to check

In Cursor settings, MCP section, vydai should have a green dot and a list of tools. Then ask in chat: “Show my VYDAI projects”.

How to disconnect

Delete the vydai block from mcp.json or turn the server off in Cursor settings.

Codex

Codex reads the key from an environment variable, so the key never lands in the config file. An environment variable is a value the system stores and passes to programs started from the terminal.

Where the settings live

  • macOS: ~/.codex/config.toml
  • Windows: %USERPROFILE%\.codex\config.toml
  • You do not need to edit the file: codex mcp add adds the entry itself.

How to connect

  1. macOS: add the line to the end of ~/.zshrc and open a new terminal.
    ~/.zshrc
    export VYDAI_API_KEY="<your key>"
  2. Windows: run the command and open a new terminal window. Windows that are already open will not see the new variable.
    Windows Command Prompt
    setx VYDAI_API_KEY "<your key>"
  3. Add the server in the new terminal:
    Terminal
    codex mcp add vydai --url https://vydai.inweb.ua/mcp --bearer-token-env-var VYDAI_API_KEY

How to check

Run codex mcp list: vydai should be on the list. Then start Codex from the same terminal and ask: “Show my VYDAI projects”.

How to disconnect

Run the command, then delete the line from ~/.zshrc or the VYDAI_API_KEY variable in Windows environment variables.

Terminal
codex mcp remove vydai

Limits

These limits protect your data and keep the service stable. If the assistant runs into one, a simple step helps: split a long period into parts or narrow the AI systems.

Read-only

The assistant cannot change prompts or settings, run a check, delete data or spend your balance. It sees only what VYDAI has already collected.

Periods up to 92 days

For visibility, competitor, source and traffic data. Dates are Kyiv calendar days, both bounds inclusive. A longer period needs several requests, one per part.

Request limits

Per key: up to 60 analytics tool calls in 5 minutes (visibility, trend, prompts, competitors, sources) and up to 300 server requests in total in 5 minutes. When the overall limit is exceeded, the server pauses the key for 5 minutes.

20 seconds per answer

If a tool does not finish within 20 seconds, the assistant gets a message that the request took too long. A shorter period or fewer AI systems help. We suggest the same if the period has more than 20,000 checks.

Balance needs full access

The balance and limits tool works only with a key that has access to all projects. A key limited to chosen projects cannot see the balance.

Shortened texts

An AI answer is passed with up to 2,000 characters, up to 15 sources per answer and up to 5 answers at a time. If an analytics response is too large, the server shortens the longest lists and marks the response as incomplete.

Whole percentages

Percentages are rounded to whole numbers, like on the VYDAI dashboard. The overall figure and per-system figures are rounded separately, so they may not match exactly.

Traffic needs GA4

Data on visits from AI sources is available only when Google Analytics 4 is connected in the project settings.

Security and data

What the assistant sees

Data from the projects available to the key (all or chosen ones): settings, prompts, check results, AI answers, competitors, sources, GEO audits and traffic, if connected. Access is checked on every request: if you are removed from a project, the assistant stops seeing it too.

What the assistant cannot see or do

Projects not chosen for the key and projects you have no access to. It changes nothing, runs no checks and does not spend your balance.

How the key is stored

We show the full key once, when you create it. The database keeps only its SHA-256 hash, which cannot be turned back into the key. Your workspace shows the key name, its first characters, expiry date and when it was last used.

Expiry and revocation

A key can be valid for 30, 90 or 365 days, or without an expiry date. You can revoke it in your workspace at any time: the server rejects the next request with that key.

Request log

We log every tool call: which key, which tool, which project, when and from which address. The log does not store the data the assistant received. It lets us see what was read if a key ends up in the wrong hands. Entries are kept for 180 days.

A separate key for each assistant

This keeps access easy to control: revoking one key does not affect the others, and your workspace shows when each one was used. Do not share your key or put it in files that go into a shared repository.

AI answers are third-party text

The answers from ChatGPT, Gemini and other systems were written neither by us nor by you. The assistant receives them marked as data, not instructions. If the assistant suggests an action based on such text, check it yourself.

Who else sees the data

Data from VYDAI becomes part of your conversation with the assistant, and the assistant's provider processes it under its own terms. Connect only the projects you are comfortable sharing with that assistant.

Troubleshooting

The most common problems and what to do about them. If nothing helps, create a new key and connect it again.

What you seeCauseWhat to do
Error 401 or unauthorizedThe key was copied incompletely, revoked or has expired, or the settings lack the Authorization: Bearer <key> header.Check the key in your workspace under “AI assistants”. If it is inactive, create a new one and replace it in the settings.
Project not found or not accessibleThe project is not chosen for this key, you no longer have access to it, or the assistant passed a wrong ID.Ask the assistant to show the project list first. If the project is missing, create a key that includes it.
The assistant does not see VYDAI toolsThe assistant was not restarted after the settings changed, the file is in the wrong place or has a syntax error (a missing or extra comma or bracket).Check the file path in the Setup section, check commas and brackets, and restart the assistant completely.
Claude Desktop does not start VYDAINode.js is not installed, so the npx command is unavailable.Install the LTS (long-term support) version from nodejs.org, check it with node -v and restart Claude Desktop.
Codex does not connect although the key is correctThe VYDAI_API_KEY variable is not set in the terminal Codex was started from.Open a new terminal, check the variable (echo $VYDAI_API_KEY on macOS, echo %VYDAI_API_KEY% in Windows Command Prompt) and start Codex from there.
Rate limit for analytics tools reachedThe key made more than 60 analytics tool calls in 5 minutes.Wait a few minutes. To stay within the limit, ask one broader question instead of many small ones.
Error 429 or Too many requestsThe key made more than 300 server requests in 5 minutes, or there were many attempts with a wrong key from your address.Wait 5–10 minutes and check that the key in your settings is correct.
Period is longer than 92 daysThe requested period is longer than 92 days.Ask the assistant to split the period into parts of up to 92 days, for example by quarter.
The request took too longThere is too much data in the period to process in 20 seconds.Shorten the period or limit the AI systems.

Questions and answers

Why do the assistant’s numbers differ from the dashboard?

Usually because of different periods. VYDAI counts Kyiv calendar days, both dates inclusive. Ask the assistant for the exact dates and AI systems it used, and set the same ones on the dashboard.

Does the assistant run a new check when I ask?

No. It reads the results VYDAI has already collected on schedule. The assistant can look up the date of the last check in the project settings.

How do I give a colleague access?

Your colleague creates their own key in their workspace. Their assistant will see only the projects they can access in VYDAI. It is better not to share your own key.

Can I connect several assistants with one key?

Technically yes, but it is better to create a separate key for each. Then revoking one does not stop the others, and your workspace shows when each was last used.

Which language does the assistant answer in?

The one you ask in. VYDAI sends data with English field names, and the assistant writes the answer in your language.

Will there be a way to connect without copying a key?

Yes, one-click connection in claude.ai and ChatGPT is planned. There are no dates yet. We will update this page when it is available.