> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.markup.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.markup.ai/_mcp/server.

# About MCP

> Connect Claude, Cursor, or any MCP client to Markup AI's hosted Model Context Protocol server at api.markup.ai/mcp/ and review content with three tools — markupai_review, markupai_run_agents, and markupai_capabilities_and_configs.

Supercharge your AI assistant with professional-grade content analysis. The **Markup AI MCP server** connects MCP clients like Claude Desktop, Claude Code, and Cursor to Markup AI's content **agents**, giving you brand-voice, clarity, persona, terminology, and AI-search checks directly in your AI-powered workflows.

## What is MCP?

**Model Context Protocol (MCP)** is an open standard that lets AI assistants call external tools and services. By connecting the Markup AI MCP server, you give your AI assistant the ability to:

* 🎯 **Check brand voice** — flag passages that have drifted from your approved voice
* 👤 **Test against a persona** — see how a target reader reacts to your content
* ✏️ **Improve clarity** — surface hard-to-read sentences with suggested rewrites
* 🤖 **Detect AI-sounding copy** — catch the giveaways of LLM-written text
* 📒 **Enforce terminology** — check content against your approved term list
* 🔍 **Get found by AI search** — check snippet readiness, sourcing, and freshness

## Three tools, fourteen agents

The server exposes **three tools**. You describe what you want checked, and the review runs the right set of agents together in a single call.

| Tool                                                                      | Use it when                                                                                                                                            |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`markupai_review`](#markupai_review)                                     | **Start here.** The user wants content reviewed, checked, or cleaned up. Optionally pass a `goal` and the server picks the agents for you.             |
| [`markupai_run_agents`](#markupai_run_agents)                             | You need an exact, deterministic set of agents—named checks, or a fixed set an integration depends on.                                                 |
| [`markupai_capabilities_and_configs`](#markupai_capabilities_and_configs) | You want to see which agents your organization can run, and which personas, voice profiles, style guides, and content profiles are available to apply. |

An **agent** is a specialized content check—brand voice, persona reaction, sentence clarity, terminology, claims, and more. Each agent runs against the settings configured for **your organization** in the [Markup AI console](https://console.markup.ai). You configure your brand voice, personas, terminology, and style guide once, and every call applies them automatically.

> **Note**
>
> Agents are addressed by their stable **name** (`brand_voice`, `sentence_clarity`, `generic_claims`, …). The names are the same ones the REST API uses, so what you learn in one carries over to the other.

## Setup

Connect to the hosted MCP server at **`https://api.markup.ai/mcp/`** from any MCP-compatible client. Add the server URL to your client and authenticate.

> **Note**
>
> Include the trailing slash (`/mcp/`). That's the canonical URL: it connects directly and returns the OAuth discovery details clients need. The no-slash form only resolves through a redirect, so prefer `/mcp/` everywhere.

You can authenticate in one of two ways:

* **Log in with your Markup AI account (OAuth).** When your client supports it, add the server and follow the browser prompt to authorize. Best for interactive use.
* **Use an API key.** Send your key in an `Authorization` header with the value `Bearer YOUR_API_KEY`. Best for headless or shared configurations.

## Prerequisites

Before you begin, ensure you have:

* An MCP-compatible client (Claude Desktop, Claude Code, Cursor, or similar)
* A Markup AI account ([sign up](https://console.markup.ai/signup)) — and an API key if your client authenticates with a header

## Quick Setup Guide

#### Create a Markup AI account

1. Visit [https://console.markup.ai/signup](https://console.markup.ai/signup) and create an account.
2. Configure your brand voice, personas, terminology, and style guide in the console—these are what the agents apply.
3. If your client authenticates with an API key, copy your key from the console and keep it handy.

> **Tip**
>
> Store your key securely. Prefer environment variables or a secrets manager over committing keys to code.

#### Add the server to your client

Point your client at `https://api.markup.ai/mcp/` and authenticate with OAuth login or an `Authorization: Bearer YOUR_API_KEY` header. Follow the client-specific guide in the [MCP Examples](#mcp-examples) section below.

#### Verify

Start a new session and confirm the three Markup AI tools appear. Try one of the [example prompts](#example-prompts).

## MCP Examples

Explore client‑specific setup guides. Each page includes configuration, restart/verify steps, and troubleshooting.

## The tools

### markupai_review

Review content against your organization's configured quality checks in one call. This is the tool your assistant should reach for whenever someone says "check this," "review this," or "clean this up before I publish."

| Parameter | Required | What it is                                                              |
| --------- | -------- | ----------------------------------------------------------------------- |
| `text`    | Yes      | The content to review. Up to 100,000 characters.                        |
| `goal`    | No       | What you're trying to achieve, in plain language. Up to 500 characters. |

**With no goal**, the standard review set runs:

```
style_agent, brand_voice, terminology, sentence_clarity,
ai_voice_detector, generic_claims, source_authority
```

**With a goal**, Markup AI composes the check set for you. Instead of naming agents, describe the outcome—"get this ranking in AI search before launch," "convince skeptical enterprise buyers," "make sure legal won't flag this"—and the server selects and orders the right agents for that goal, on top of the standard set. It also asks the agents that support it to focus their findings on your goal.

> **Tip**
>
> A goal only ever **adds** checks—it never drops one from the standard set. So passing a goal is always at least as thorough as leaving it out. If goal selection is unavailable for any reason, the standard set runs anyway and the response says so in `warnings`.

### markupai_run_agents

Run an explicit, fixed set of agents. Use this when the user names specific checks, or when an integration needs the same agents every time.

| Parameter | Required | What it is                                                                           |
| --------- | -------- | ------------------------------------------------------------------------------------ |
| `agents`  | Yes      | 1–20 agent names, e.g. `["brand_voice", "generic_claims"]`.                          |
| `text`    | Yes      | The content to run them against. Up to 100,000 characters.                           |
| `config`  | No       | Overrides for the configuration this run applies (see below).                        |
| `goal`    | No       | Focuses findings within the agents you named. It never changes or reorders your set. |

Your organization's configured profiles and guides apply unless you override them:

| `config` key      | What it sets                                                            |
| ----------------- | ----------------------------------------------------------------------- |
| `persona`         | The persona the `persona` agent reads as—by name or ID.                 |
| `voice_profile`   | The brand voice profile `brand_voice` evaluates against.                |
| `style_guide`     | The style guide `style_agent` applies.                                  |
| `content_profile` | The content profile `style_agent` uses (e.g. Markdown, HTML, DITA).     |
| `domain_ids`      | Up to 20 terminology domains for `terminology` and `ai_voice_detector`. |

Get valid names and IDs from [`markupai_capabilities_and_configs`](#markupai_capabilities_and_configs).

> **Note**
>
> `markupai_review` and `markupai_run_agents` divide the work cleanly: **review** decides what to check, **run_agents** does exactly what it's told. For any general "is this good?" ask, prefer `markupai_review`—it makes better choices than a hand-picked list, and it explains the choices it made.

### markupai_capabilities_and_configs

Pull down everything your organization has configured, in one read-only call with no arguments:

* **agents** — name, one-line description, and category for every agent you can run
* **personas** — ID, name, and title
* **voice_profiles** — ID and name
* **style_guides** — ID and name
* **content_profiles** — ID and name

It returns a compact catalog—names and one-line descriptions, no JSON schemas. You rarely need it before `markupai_review`, which applies your configuration automatically; it's most useful when you're about to override something in `markupai_run_agents`.

> **Note**
>
> If your account can't read a section—personas, say—that section comes back as an empty list plus a `warnings` entry explaining why, rather than failing the whole call.

## Available agents

Every agent below can be named in `markupai_run_agents`, and any of them can be selected by `markupai_review` when your goal calls for it. Which ones your organization can actually run depends on your plan and feature access—check with `markupai_capabilities_and_configs`.

| Agent name           | Catalog page                                       | Category          | What it flags                                                                                                                                                    |
| -------------------- | -------------------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `style_agent`        | [Style](/agents/style-agent)                       | Brand             | Your whole style guide in one pass—passive voice, word choice, consistency, readability. Also returns quality scores when your organization has scoring enabled. |
| `brand_voice`        | [Brand Voice](/agents/brand-voice)                 | Brand             | Passages whose tone or phrasing has drifted from your approved brand voice.                                                                                      |
| `terminology`        | [Brand Terms](/agents/terminology)                 | Brand             | Unapproved words and phrases, with preferred replacements from your term list.                                                                                   |
| `persona`            | [Persona](/agents/persona)                         | Brand             | Where a defined ICP persona would lose interest, get confused, or stop trusting you.                                                                             |
| `sentence_clarity`   | [Sentence Clarity](/agents/sentence-clarity)       | Content Integrity | Hard-to-read sentences, with clearer rewrites.                                                                                                                   |
| `ai_voice_detector`  | [AI Voice](/agents/ai-voice-detector)              | Content Integrity | Writing patterns that signal AI generation—clichés, uniform rhythm, repetitive structure.                                                                        |
| `focus_agent`        | [Fluff](/agents/focus-agent)                       | Content Integrity | Indirect, filler, and off-topic sentences that bury your point.                                                                                                  |
| `generic_claims`     | [Claims](/agents/generic-claims)                   | Accuracy          | Verifiable claims and promissory language that could create exposure.                                                                                            |
| `date_time_accuracy` | [Date & Time Accuracy](/agents/date-time-accuracy) | Accuracy          | Impossible dates, weekday mismatches, inverted or contradictory date ranges, bad timezone conversions, and missing timezone or AM/PM information.                |
| `link_integrity`     | [Link Integrity](/agents/link-integrity)           | Accuracy          | Anchor/URL mismatches, dead destinations, decayed domains, misattributed citations, and off-topic links.                                                         |
| `source_authority`   | [Source Authority](/agents/source-authority)       | AI Visibility     | Content missing the credibility signals AI models look for when choosing what to cite.                                                                           |
| `snippet_readiness`  | [Snippet Readiness](/agents/snippet-readiness)     | AI Visibility     | Sections that don't stand alone when an AI system extracts them.                                                                                                 |
| `answer_authority`   | [Q\&A Optimization](/agents/answer-authority)      | AI Visibility     | Headings and answers that don't lead with the answer.                                                                                                            |
| `key_takeaways`      | [Key Takeaways](/agents/key-takeaways)             | AI Visibility     | A missing key-takeaways summary near the top of the document.                                                                                                    |
| `freshness`          | [Freshness](/agents/freshness)                     | AI Visibility     | Stale content, outdated references, and missing freshness signals.                                                                                               |

## What you get back

Both execute tools return the same **evidence envelope**, so your assistant always knows what actually ran—not just what was found:

```json
{
  "checked": {
    "agents_run": ["style_agent", "brand_voice", "terminology"],
    "selection": "default",
    "voice_profile": "Markup AI",
    "style_guide": "Technical",
    "persona": null,
    "characters": 1840
  },
  "warnings": [],
  "results": [
    {
      "agent": "brand_voice",
      "issues": [
        {
          "agent": "brand_voice",
          "severity": "medium",
          "confidence": 0.82,
          "explanation": "Hedged phrasing undercuts the confident voice.",
          "position": { "start": 412, "end": 448, "text": "we think this might help" },
          "category": "tone",
          "suggestion": "this helps"
        }
      ]
    }
  ],
  "duration_seconds": 12.4
}
```

Worth knowing:

* **`checked.selection`** tells you how the agent set was chosen: `default` (standard set), `goal` (composed from your goal), or `explicit` (you named them).
* **`checked.goal`** appears only when you passed a goal, and shows how it was interpreted—the agents it added and the resulting plan.
* **Configuration evidence is honest.** `voice_profile`, `style_guide`, and `persona` are populated only when an agent that consumes them actually ran.
* **`warnings` are never stripped.** An unconfigured voice profile, an agent your plan gates out, or a partial failure shows up here with a code and explanation—so an empty result is never mistaken for a clean bill of health.
* **`results` has one entry per agent that completed**, even when the agent found nothing. Agents that fail appear as `agent_failed` warnings instead.
* **`scores`** appear inside the `style_agent` entry when your organization has numeric scoring enabled.

## Example prompts

### Review before publishing

```
Review this launch announcement before I publish it: [paste text]
```

### Review with a goal

```
Review this page with the goal of getting it cited by AI search assistants: [paste text]
```

```
Check this landing page copy—my goal is to convince skeptical enterprise buyers: [paste text]
```

### Named checks only

```
Run just brand voice and claims on this paragraph: [paste text]
```

### Check against a specific persona

```
Run the persona agent on this post as Casey, our Head of Technical Documentation: [paste text]
```

### See what's configured

```
What Markup AI agents, personas, and style guides do we have available?
```

## Per-agent tool names

Some clients and saved configurations reference a tool name per agent. Those names map onto the three-tool surface like this:

| Tool name                                                                                                    | Equivalent call                                                                                         |
| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| `markupai_brand_voice`                                                                                       | `markupai_run_agents` with `agents: ["brand_voice"]`                                                    |
| `markupai_persona`                                                                                           | `markupai_run_agents` with `agents: ["persona"]`                                                        |
| `markupai_sentence_clarity`                                                                                  | `markupai_run_agents` with `agents: ["sentence_clarity"]`                                               |
| `markupai_ai_voice`                                                                                          | `markupai_run_agents` with `agents: ["ai_voice_detector"]`                                              |
| `markupai_brand_terms`                                                                                       | `markupai_run_agents` with `agents: ["terminology"]`                                                    |
| `markupai_style`                                                                                             | `markupai_run_agents` with `agents: ["style_agent"]`                                                    |
| `markupai_claims`                                                                                            | `markupai_run_agents` with `agents: ["generic_claims"]`                                                 |
| `markupai_date_time_accuracy`                                                                                | `markupai_run_agents` with `agents: ["date_time_accuracy"]`                                             |
| `markupai_link_integrity`                                                                                    | `markupai_run_agents` with `agents: ["link_integrity"]`                                                 |
| `markupai_fluff`                                                                                             | `markupai_run_agents` with `agents: ["focus_agent"]`                                                    |
| `markupai_freshness`                                                                                         | `markupai_run_agents` with `agents: ["freshness"]`                                                      |
| `markupai_key_takeaways`                                                                                     | `markupai_run_agents` with `agents: ["key_takeaways"]`                                                  |
| `markupai_q_and_a_optimization`                                                                              | `markupai_run_agents` with `agents: ["answer_authority"]`                                               |
| `markupai_snippet_readiness`                                                                                 | `markupai_run_agents` with `agents: ["snippet_readiness"]`                                              |
| `markupai_source_authority`                                                                                  | `markupai_run_agents` with `agents: ["source_authority"]`                                               |
| `markupai_list_agents`, `markupai_get_agent`, `markupai_list_personas`, `markupai_list_brand_voice_profiles` | `markupai_capabilities_and_configs`                                                                     |
| `markupai_execute_agent_sync`                                                                                | `markupai_run_agents`, naming the agents                                                                |
| `markupai_execute_agent_async`, `markupai_get_workflow_status`                                               | `markupai_run_agents`. Runs are synchronous—see [Troubleshooting](#troubleshooting) for long documents. |

Two related points:

* **MCP addresses agents by catalog name.** Pass an unknown name and the error lists every valid one. The REST API addresses agents by `ag_` ID.
* **MCP has no `webhook_url` parameter.** The REST API supports webhooks.

> **Tip**
>
> A single `markupai_review` call covers what a chain of per-agent calls covers, and picks the agents for you. Reach for the mapping above only when you need one specific check.

## Troubleshooting

#### Markup AI tools not showing in your client

1. Confirm the server URL is `https://api.markup.ai/mcp/`.
2. Make sure you completed authentication—either the OAuth login prompt or an `Authorization: Bearer YOUR_API_KEY` header.
3. Completely quit your MCP client (cmd+Q on Mac, not just closing the window) and reopen it.
4. You should see exactly three tools. If you see a longer list of per-agent tools, your client is serving a cached tool list—reconnect the server.

#### Getting 'unauthorized' or 401 errors

1. If using an API key, verify it's correct (no extra spaces or quotes) and sent as `Authorization: Bearer YOUR_API_KEY`.
2. If using OAuth, reconnect/re-authorize the server from your client and complete the browser prompt.
3. If it still fails with a freshly copied key, confirm your account is active and has API access. The server returns the same `401` for any token problem—missing, malformed, or expired—so it won't tell you which; re-check these one at a time.

#### An agent I expect doesn't run

Check the `warnings` in the response—it will name the agent and the reason. The agents you can run depend on your organization's plan and feature access, and some require features to be enabled in the [console](https://console.markup.ai). Run `markupai_capabilities_and_configs` to see exactly what your account can run.

#### An agent reports no issues and I don't trust it

That's what the envelope is for. Check `checked.agents_run` to confirm the agent ran, and `checked.voice_profile` / `checked.style_guide` / `checked.persona` to confirm the configuration it applied. If a profile you expected shows as `null`, it wasn't configured—look for the matching `warnings` entry (e.g. `voice_profile_not_configured`). A clean result with full evidence really is clean.

#### Long documents and timeouts

Runs are synchronous and bounded by a server-side deadline, so very long documents can time out. `text` accepts up to 100,000 characters, but for large content split it into sections and review them separately—section-level results are easier to act on anyway. There's no async mode or polling on MCP; if you need background runs or webhooks, use the [REST API](https://docs.markup.ai).

#### A goal doesn't change what runs

A goal composes checks **up**, never down—it can add agents to the standard set but won't remove any. If you need a narrower run, name the agents explicitly with `markupai_run_agents`. Also check `checked.goal` in the response to see how your goal was interpreted, and `warnings` for any note that goal selection fell back to the standard set.

## Tips for Success

> **Tip**
>
> **Lead with the goal, not the agent list**: Tell your assistant what you're trying to achieve and let `markupai_review` compose the checks. Naming agents yourself is for when you need determinism, not for everyday review.

> **Tip**
>
> **Configure once, apply everywhere**: Set your brand voice, personas, terminology, and style guide in the [console](https://console.markup.ai). Every call applies them automatically—no per-request configuration needed.

> **Tip**
>
> **Read the evidence**: The `checked` block tells you what ran and against which profiles. When a result surprises you, it's usually the fastest explanation.

## Learn More

* 📚 [MCP Documentation](https://modelcontextprotocol.io/) — Understand the protocol powering this integration
* 🧠 [Agent Catalog](/agents) — What each agent checks and why it matters
* 🚀 [Markup AI API Docs](https://docs.markup.ai) — Explore all API capabilities
* 🛠️ [Markup AI Console](https://console.markup.ai) — Configure your brand voice, personas, terminology, and style guide

Ready to transform your writing? Connect the Markup AI MCP server and bring AI-powered content checks into your assistant.