# MCP Server

Connect Claude, ChatGPT, Codex, Cursor or another AI app to your Senso knowledge base and AI visibility.

The Senso [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server lets an AI app work with your Senso account. Once it is connected, you can ask the app to search and edit your knowledge base, or to look at your AI visibility: the prompts you track, the pages AI answers cite, your competitors, and the claims your knowledge base does not back up.

## What you can do

Ask in your own words. For example:

| Ask your app | What you get back |
|--------------|-------------------|
| "How visible are we in AI answers this month?" | How often AI answers name your organization and cite its websites, against the previous period |
| "How do we compare with our competitors in ChatGPT answers?" | Your organization and the competitors you track, side by side |
| "Which pages do AI answers cite most for our prompts?" | The pages or domains AI answers cite, most cited first |
| "Which claims in AI answers does our knowledge base not back up?" | Claims your knowledge base contradicts or does not support |
| "What does our knowledge base say about our refund policy?" | An answer drawn from the documents in your knowledge base |
| "Add a document called Shipping FAQ saying we ship within 3 business days." | A new document in your knowledge base |

## Before you start

- **A Senso account** that belongs to at least one organization.
- **An AI app that can connect to a remote MCP server** and sign in with OAuth. Every app below can.
- **Tracked prompts with finished runs,** for AI visibility figures. Until your organization's first runs finish, the visibility tools have nothing to report.

## Set up Senso MCP

Pick the app you use. Claude and ChatGPT are set up in the browser; Claude Code and Codex need one command in your terminal; Cursor and VS Code take one click. Whichever you choose, you finish by signing in to Senso and choosing what the app may do. See [Sign in and choose permissions](#sign-in-and-choose-permissions).

### Claude
Add Senso as a custom connector. It then works in Claude on the web and in the Claude desktop app.

1. In Claude, open **Customize**, then **Connectors**.
2. Select **+ Add**, then **Add custom connector**.
3. Name it **Senso**, paste `https://apiv2.senso.ai/mcp` as the URL, and select **Continue**.
4. Keep the suggested settings on the next screens, selecting **Continue** and then **Add**.
5. Sign in to Senso in the window that opens. If no window opens, select **Connect** beside Senso.

To use it, select the **Add** button in a chat, then **Connectors**, and turn on **Senso**.

On a Free plan you can add one custom connector. On a Team or Enterprise plan, an owner adds the connector for everyone first, under **Organization settings**, then **Connectors**. Each person then finds Senso under **Customize**, then **Connectors**, and selects **Connect**.
### ChatGPT
Add Senso as a custom plugin. This is done in ChatGPT on the web.

1. Go to [chatgpt.com/plugins](https://chatgpt.com/plugins).
2. Select the **Add** button, then **Add custom MCP server**.
3. Name it **Senso**. Under **Connection**, paste `https://apiv2.senso.ai/mcp` as the server URL.
4. Choose **OAuth** as the authentication.
5. Read the warning, select **I understand and want to continue**, then **Create as a plugin**.
6. Find Senso in your plugins, install it, and sign in to Senso in the window that opens.

To use it, type **@** in a chat and choose **Senso**.

In a Business, Enterprise or Edu workspace, your workspace settings decide whether you can add custom plugins. If you cannot see the option, ask your ChatGPT admin.
### Claude Code
Open your terminal and run this command to add Senso to Claude Code:

```bash
claude mcp add --transport http --scope user senso https://apiv2.senso.ai/mcp
```

Then run this command to sign in. Your browser opens the Senso sign-in page:

```bash
claude mcp login senso
```

`--scope user` makes Senso available in every project on your computer. To add it to the current project only, leave `--scope user` out.

For more information, see the [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp).
### Codex
Open your terminal and run this command to add Senso to Codex:

```bash
codex mcp add senso --url https://apiv2.senso.ai/mcp
```

Your browser opens the Senso sign-in page. If it does not, or you need to sign in again later, run:

```bash
codex mcp login senso
```

The ChatGPT desktop app, the Codex command line and the Codex extension for your code editor share this setup, so you only add Senso once. To learn more, see the OpenAI [Codex MCP documentation](https://learn.chatgpt.com/docs/extend/mcp).
### Cursor
[Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=senso&config=eyJ1cmwiOiJodHRwczovL2FwaXYyLnNlbnNvLmFpL21jcCJ9)

Select **Add to Cursor**. Cursor opens and asks you to confirm adding Senso. When Cursor asks you to sign in, your browser opens the Senso sign-in page.

You can turn Senso on or off later from **Customize** in Cursor's sidebar.

To set it up by hand instead, add the following to `~/.cursor/mcp.json` for every project, or to `.cursor/mcp.json` in one project:

```json
{
  "mcpServers": {
    "senso": {
      "url": "https://apiv2.senso.ai/mcp"
    }
  }
}
```

For more information, see [Cursor's MCP documentation](https://cursor.com/docs/mcp).
### VS Code
[Install in VS Code](https://vscode.dev/redirect/mcp/install?name=senso&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapiv2.senso.ai%2Fmcp%22%7D)

Select **Install in VS Code**. VS Code opens and asks you to confirm adding Senso. The first time Senso is used, your browser opens the Senso sign-in page.

VS Code uses Senso from GitHub Copilot Chat, so you need Copilot set up in VS Code.

To set it up by hand for one project instead, add the following to `.vscode/mcp.json` in that project:

```json
{
  "servers": {
    "senso": {
      "type": "http",
      "url": "https://apiv2.senso.ai/mcp"
    }
  }
}
```

For more information, see the [VS Code MCP documentation](https://code.visualstudio.com/docs/agent-customization/mcp-servers).
### Other
Most AI apps that support MCP can add a remote MCP server. Look for that option in your app's settings, and use:

- **URL:** `https://apiv2.senso.ai/mcp`
- **Authentication:** OAuth

Your app needs to support OAuth sign-in for remote MCP servers. It finds everything else from the URL.

For developers: the server speaks Streamable HTTP and is stateless. It issues no session ID, accepts `POST` only, and answers with `application/json` rather than an event stream.

## Sign in and choose permissions

The first time your app connects, it opens the Senso sign-in page in your browser. There you:

1. **Sign in** with your Senso account.
2. **Choose organizations.** Pick one, several, or all of the organizations you belong to. The app can work in those and no others.
3. **Choose permissions.** Reading is allowed by default. Tick a permission below to let the app make changes or delete things.
4. **Approve.** You go back to your app, which stays connected until you remove it.

**The app acts as you.** It can only do what you can do in Senso, and only within the permissions you ticked. If you can't see a folder in Senso, neither can the app.

**Searches are saved.** Each knowledge base search the app runs is saved to your organization's search history, and Senso uses that history to find gaps in your knowledge base. Senso receives what the app sends to a tool, never the rest of your conversation.

**If you chose more than one organization,** say which one you mean when you ask, for example "In Acme, find our refund policy." To add an organization later, connect your app again and select it. The permissions you already gave stay ticked.

### Permissions

| Permission | Technical name | What it allows |
|------------|----------------|----------------|
| **Read documents** | `kb.read` | Search the knowledge base and read documents |
| **Create and edit documents** | `kb.write` | Add and change documents, folders and tags |
| **Delete documents and folders** | `kb.delete` | Delete documents and folders. Deleting a folder deletes everything inside it |
| **Read AI visibility and the organization** | `visibility.read` | See prompts, competitors, citations, answer gaps, tracked pages, reports, the brand kit, product lines, and members' names and emails |
| **Manage AI visibility** | `visibility.write` | Add and change prompts, competitors, the brand kit and product lines; track pages and approve verified sources; record verdicts on claims and start fact checks |
| **Delete prompts, competitors and product lines** | `visibility.delete` | Stop tracking prompts, remove competitors and delete product lines. This cannot be undone |

Deleting is a separate permission on purpose, so an app you let edit documents cannot also empty your knowledge base. If you later ask for something you did not allow, most apps ask you to sign in to Senso again so you can allow it.

## Manage connections

Every app you connect is listed in the Senso app.

| Who | Where | What removing does |
|-----|-------|--------------------|
| You | **Profile**, under **My connections** | Disconnects the app from all your organizations |
| An organization admin | **Settings**, then **Connections** | Removes that organization from the app's connection. Any other organizations it was given stay connected |

The app loses access as soon as it is removed.

## Tools

The server exposes 53 [MCP tools](https://modelcontextprotocol.io/docs/concepts/tools). Every tool except `senso_list_orgs` takes an `org_id`. Turn on your app's setting to approve tool calls before they run, and take care when using Senso alongside other MCP servers, to avoid prompt injection.

Tools marked **Asks first** take `confirm: true`. They change something for the whole organization, start charged work, or cannot be undone, and the agent is told to describe what will happen and set `confirm` only after you agree. Claude Code also asks you before each call to them, whatever your permission settings.

### Organization

| Tool | Scope | What it does |
|------|-------|--------------|
| `senso_list_orgs` | any | List the organizations this connection can act on. Call it first |
| `senso_get_org` | `visibility.read` | How the organization is set up: industry, websites, markets, AI models, run days, competitors |
| `senso_list_members` | `visibility.read` | The organization's members, with each one's user id, name and email |

### Knowledge base

| Tool | Scope | What it does |
|------|-------|--------------|
| `senso_search` | `kb.read` | Search the knowledge base by meaning. Uses organization credits |
| `senso_list` | `kb.read` | List a folder's contents. Omit `node_id` for the root |
| `senso_find` | `kb.read` | Find documents and folders by name |
| `senso_get_doc` | `kb.read` | Read a document's text, title, summary, version and processing status |
| `senso_create_doc` | `kb.write` | Add a markdown or plain text document |
| `senso_update_doc` | `kb.write` | Change a document's title, summary or text. New text replaces the whole body |
| `senso_create_folder` | `kb.write` | Create a folder |
| `senso_rename_node` | `kb.write` | Rename a document or folder |
| `senso_move_node` | `kb.write` | Move a document or folder into another folder |
| `senso_tag_doc` | `kb.write` | Set a document's tags, replacing the ones it has |
| `senso_delete_node` | `kb.delete` | Delete a document or folder, and everything in a folder. **Asks first** |

### AI visibility

| Tool | Scope | What it does |
|------|-------|--------------|
| `senso_get_filters` | `visibility.read` | The AI models, markets, funnel stages, topics, personas and periods the other tools filter by. Call it before them |
| `senso_get_visibility` | `visibility.read` | How often AI answers name the organization and cite its websites, against the previous period |
| `senso_get_competition` | `visibility.read` | How the organization compares with its competitors in AI answers |
| `senso_list_prompts` | `visibility.read` | The prompts the organization tracks, with each one's figures |
| `senso_get_prompt` | `visibility.read` | One prompt in full: figures per AI model, brands named, pages cited and newest answers |
| `senso_get_answer` | `visibility.read` | One AI model's newest answer to a prompt, with the brands, citations and fact check |
| `senso_list_industry_prompts` | `visibility.read` | The prompts of the organization's industry, with the brands their answers name and whether the organization already tracks each one |
| `senso_list_citations` | `visibility.read` | The pages or domains AI answers cited, most cited first |
| `senso_get_citation_trend` | `visibility.read` | One cited page's citations per day |
| `senso_list_citing_prompts` | `visibility.read` | The prompts whose answers cited a page |
| `senso_list_problems` | `visibility.read` | Problems in how AI answers treat the organization, most serious first |
| `senso_list_tracked_pages` | `visibility.read` | Tracked pages, with their citations, page checks and verification status |
| `senso_list_reports` | `visibility.read` | Reports and report schedules |
| `senso_get_brand_kit` | `visibility.read` | The brand kit generated content follows |
| `senso_list_product_lines` | `visibility.read` | The organization's product lines |
| `senso_add_prompts` | `visibility.write` | Track up to 100 new prompts. Their runs are charged to organization credits. **Asks first** |
| `senso_import_industry_prompts` | `visibility.write` | Track up to 100 of the industry's prompts, with the last 7 days of answers already collected for them. Their runs are charged to organization credits. **Asks first** |
| `senso_update_prompt` | `visibility.write` | Change a prompt's funnel stage |
| `senso_set_competitor` | `visibility.write` | Add a competitor, or change one's name or website |
| `senso_set_problem_status` | `visibility.write` | Dismiss, snooze or reopen a problem |
| `senso_track_page` | `visibility.write` | Track a web page, or stop tracking it |
| `senso_start_verification` | `visibility.write` | Start verifying one of the organization's own pages as a verified source |
| `senso_approve_source` | `visibility.write` | Approve a page as a verified source. **Asks first** |
| `senso_withdraw_source` | `visibility.write` | Withdraw a verified source's approval. **Asks first** |
| `senso_update_brand_kit` | `visibility.write` | Change the brand kit for all content generated from now on. **Asks first** |
| `senso_add_product_lines` | `visibility.write` | Add up to 50 product lines |
| `senso_update_product_line` | `visibility.write` | Change a product line's name or details. **Asks first** |
| `senso_delete_prompt` | `visibility.delete` | Stop tracking a prompt. **Asks first** |
| `senso_remove_competitor` | `visibility.delete` | Stop tracking a competitor. **Asks first** |
| `senso_delete_product_line` | `visibility.delete` | Delete a product line. **Asks first** |

### Answer gaps and fact checks

| Tool | Scope | What it does |
|------|-------|--------------|
| `senso_list_claim_gaps` | `visibility.read` | Claims in AI answers or on web pages that the knowledge base contradicts or does not back up |
| `senso_get_claim_trend` | `visibility.read` | Open claims about the organization per day |
| `senso_list_claim_verdicts` | `visibility.read` | The verdicts recorded on claims that still stand |
| `senso_get_claim_verdict` | `visibility.read` | One recorded verdict |
| `senso_check_prompt_answers` | `visibility.write` | Fact-check the latest AI answers to up to 20 prompts. Uses no credits |
| `senso_check_page` | `visibility.write` | Fact-check any public web page against the knowledge base. Uses no credits |
| `senso_assign_claims` | `visibility.write` | Assign claims to a member, or clear the assignee |
| `senso_record_claim_verdict` | `visibility.write` | Record a verdict on claims for everyone in the organization. **Asks first** |
| `senso_undo_claim_verdict` | `visibility.write` | Undo a recorded verdict |

## Limits

| Limit | Value |
|-------|-------|
| Requests | 60 per minute per connection, counted across every server. Over it, the server answers `429` with a `Retry-After` header |
| Credits | `senso_search`, creating or updating a document, and the prompt runs `senso_add_prompts` and `senso_import_industry_prompts` start are charged to organization credits. Out of credits or over its spending limit, a search or a document change is refused and retrying will not help |

A tool that fails returns a readable message rather than an opaque code, so the agent can correct itself. An organization, document or folder that does not exist and one you cannot access get the same message, so nobody can probe for what exists.

## Troubleshooting

| Problem | What to do |
|---------|------------|
| The Senso sign-in page does not open | In Claude, select **Connect** beside Senso. In Claude Code, run `claude mcp login senso`. In Codex, run `codex mcp login senso` |
| Senso will not connect on a work computer or network | Ask your IT team to allow `apiv2.senso.ai` |
| The app says it is not allowed to do something | You did not tick that permission when you connected: connect again and tick it, and the permissions you already gave stay ticked. Or your role in Senso does not allow it: ask your organization admin |
| The app cannot find an organization | You did not choose it when you connected. Connect again and select it. You can only choose organizations you belong to |
| The AI visibility tools return no figures | Your organization has no tracked prompts with finished runs yet. Figures appear once the first runs finish |
| A search or a document change is refused for credits | Your organization is out of credits or has reached its spending limit, so retrying will not help. Ask your organization admin, or email [support@senso.ai](mailto:support@senso.ai) |
| A document or folder "does not exist" | It does not exist, or you cannot access it. Senso gives both the same message on purpose. Check that you can open it in the Senso app |
| The app is told to slow down | The app sent more than 60 requests in a minute. The app can try again after the time in the `Retry-After` header |

## Get help

Email [support@senso.ai](mailto:support@senso.ai), and say which app you connected and which tool failed. See [Support](https://docs.senso.ai/docs/support) for what else to include.