---
title: "MCP & API — Menciona"
description: "Query your AI visibility data programmatically with the Menciona MCP server."
lang: en-US
---
# MCP & API — Menciona

Menciona ships an MCP server, so your data is available programmatically — not locked in a dashboard.

## What is MCP?

The Model Context Protocol lets AI assistants call tools directly. With the Menciona MCP server connected, your assistant can read and update your visibility data.

## What you can do

- Projects: create and manage the brands you track.
- Prompts: list, create, and update the prompts you monitor.
- Audits: pull site audit results, checks, and recommendations.
- Brand visibility: read your mention rate and sentiment.
- Competitors: compare visibility and trends.
- Keywords: see which keywords surface your brand.
- Sources: see which domains drive your citations.

## Connect it

The MCP server works with MCP-compatible AI assistants. Find setup steps in your account.

## Drive it directly over HTTP

If your agent speaks HTTP but has no built-in MCP client, call the server directly. It is **JSON-RPC 2.0 over StreamableHTTP** at `https://api.menciona.ai/mcp`. Every request needs three headers:

- `Authorization: Bearer menciona_…` — your API key
- `Content-Type: application/json`
- `Accept: application/json, text/event-stream`

**1. Initialize the session**

```bash
curl https://api.menciona.ai/mcp \
  -H "Authorization: Bearer menciona_…" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}'
```

**2. Discover the tools** — don't guess tool names, list them:

```bash
curl https://api.menciona.ai/mcp \
  -H "Authorization: Bearer menciona_…" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
```

This returns every tool with its input schema — projects, prompts, audits, brand_visibility, competitors, sources, keywords, tags, `account.usage`, and **`feedback.submit`** (use it to report a bug or relay a message to the Menciona team). All tool params and response fields are **snake_case**.

**3. Call a tool**

```bash
curl https://api.menciona.ai/mcp \
  -H "Authorization: Bearer menciona_…" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"projects.create","arguments":{"name":"Cal.com","url":"https://cal.com","brand_name":"Cal.com","surfaces":["google-ai-overview","chatgpt","gemini"]}}}'
```

The `surfaces` array is **required** and must list at least 3 of the available AI surfaces to monitor: `google-ai-overview`, `chatgpt`, `gemini`, `google-ai-mode`. (Read the `menciona://schema/surfaces` resource for the authoritative list.)

**4. Add prompts** — the prompt text goes in the **`text`** field:

```bash
curl https://api.menciona.ai/mcp \
  -H "Authorization: Bearer menciona_…" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"prompts.create","arguments":{"project_id":"<from projects.list>","text":"What are the best scheduling tools?"}}}'
```

**Reading responses:** tool results use the MCP envelope — the payload is a JSON string inside `result.content[0].text`, so parse that inner string to get the actual object. A tool error sets `result.isError: true` with the message in the same `text` field.

**Waiting for work:** creating a project starts its first audit and creating a prompt starts its first run, in the background. An audit is usually ready in under a minute; poll `audits.list` / `audits.get` until `status` is `done`. Prompt results take longer — `brand_visibility.get` returns `empty_reason: "no_runs_yet"` until the first run lands, so poll rather than treating it as "no data".

Start your free trial: https://app.menciona.ai/signup