Surva.ai MCP server reference

The Surva.ai MCP server lets any Model Context Protocol client read a Surva.ai account's AI search visibility data and, with permission, add prompts and competitors. This page covers connection, authentication, every tool, limits and protocol behavior.

Overview

Server URL

https://app.surva.ai/mcp

Transport

Streamable HTTP, POST only, JSON responses, stateless

Protocol versions

2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05

Capabilities

tools, prompts

Read tools return data Surva.ai has already collected on its scheduled refreshes. They never trigger new AI queries, so results match the Surva.ai dashboard and cost nothing beyond your plan. Every result includes app_link URLs into the web app.

Quick start

Clients with OAuth support only need the server URL. Signed-in users get step-by-step instructions in Settings, AI assistants.

claude mcp add --transport http surva https://app.surva.ai/mcp

{
  "mcpServers": {
    "surva": { "url": "https://app.surva.ai/mcp" }
  }
}

{
  "servers": {
    "surva": { "type": "http", "url": "https://app.surva.ai/mcp" }
  }
}

{
  "mcpServers": {
    "surva": {
      "url": "https://app.surva.ai/mcp",
      "headers": { "Authorization": "Bearer sva_pat_..." }
    }
  }
}

Authentication

Every request except server/discover needs a bearer token in the Authorization header. Unauthenticated requests get 401 with a WWW-Authenticate header pointing to the protected resource metadata, which is how MCP clients start OAuth automatically.

OAuth 2.1

• Authorization code grant with PKCE (S256 only). Public clients; no client secret.
• Client registration: Client ID Metadata Documents (an HTTPS client_id URL) are preferred. Dynamic Client Registration (RFC 7591) is supported for older clients.
• Redirect URIs must be HTTPS, loopback HTTP (http://127.0.0.1, http://localhost, any port) or a private-use scheme such as cursor://.
• Send resource=https://app.surva.ai/mcp (RFC 8707). Authorization responses include iss (RFC 9207).
• Access tokens last 60 minutes. Refresh tokens last 60 days and rotate on every use.
• The consent screen lets the user pick an account or a single brand and decide whether to allow changes.

Personal access tokens

For scripts, agents and clients without OAuth. Create them in Settings, AI assistants. Tokens start with sva_pat_, act as the user who created them, and work until revoked. Surva.ai stores only a SHA-256 hash, so a lost token cannot be recovered; create a new one.

Scopes and brand access

A connection covers either every brand in one account or a single brand. Brand-specific tools take an optional brand argument (ID, name or domain). Without it, the server uses the connection's only brand, then the user's current brand, then the account's first brand. Call list_brands to see what a connection can reach.

Tools

All tools return a JSON object as structuredContent and the same JSON as a text content block. Tools are listed in alphabetical order and annotated with readOnlyHint, idempotentHint and destructiveHint: false.

Read tools

Write tools (scope: write)

Prompts

Prompt templates appear in clients as slash commands or quick actions and guide the assistant through the right tools.

• competitor_deep_dive

  Compare one competitor against your brand across AI answers, citations, ads and organic search.

  Arguments: competitor (required), brand

• content_gap_plan

  Turn the prompts where AI recommends competitors instead of you into a prioritized content plan.

  Arguments: brand, count

• investigate_prompt

  Explain why AI engines do or do not recommend your brand for a specific buyer question.

  Arguments: prompt (required), brand

• weekly_ai_visibility_report

  A one-page summary of how ChatGPT, Perplexity, Claude, Gemini and Google AI Overviews talk about your brand this week.

  Arguments: brand

Limits

Limits apply per Surva.ai account across all of its connections. Up to 60 tool calls per minute, plus a daily allowance by plan that resets at midnight:

Write tools also count toward the plan's prompt and competitor limits, exactly as in the web app. Listing tools and prompts does not count toward limits.

Errors

Protocol details

• Modern clients (2026-07-28): stateless. Send the version in params._meta["io.modelcontextprotocol/protocolVersion"] and mirror it in the MCP-Protocol-Version header, with Mcp-Method on every request and Mcp-Name on tools/call and prompts/get. server/discover is available without authentication. Results carry resultType, list results carry ttlMs and cacheScope.
• Earlier clients (2024-11-05 to 2025-11-25): the initialize handshake and ping work as before. The server does not issue Mcp-Session-Id; requests are independent and can hit any server instance.
• There is no GET stream. GET and DELETE on the endpoint return 405. All responses are single JSON objects.
• Tools and prompts do not change at runtime, so listChanged is false.

Raw HTTP example

Call a tool with a personal access token:

curl https://app.surva.ai/mcp \
  -H "Authorization: Bearer $SURVA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/call" \
  -H "Mcp-Name: get_visibility_overview" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"get_visibility_overview","arguments":{"brand":"acme.com"},
                 "_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28"}}}'

Response (shortened):

{"jsonrpc":"2.0","id":1,"result":{
  "content":[{"type":"text","text":"{\"brand\":{\"name\":\"Acme\",...}}"}],
  "structuredContent":{
    "brand":{"id":"...","name":"Acme","domain":"acme.com"},
    "summary":{"ai_visibility_percent":42.5,"share_of_voice_percent":18.2,"tracked_prompts":40},
    "visibility_by_engine_percent":{"ChatGPT":48,"Perplexity":51,"Claude":35,"Gemini":30},
    "app_link":"https://app.surva.ai/ai-visibility"
  },
  "isError":false,
  "resultType":"complete"
}}