Thematic Admin MCP Server

The Thematic Admin MCP server lets you edit your theme structure by talking to an AI assistant. It is the write counterpart to the Thematic MCP server, which reads your results.

Once connected, the assistant has 20 tools to read your themes, find problems in them, propose fixes, test a change against your real data, and publish it. You can ask things like "which of our themes overlap?" or "what would happen if I mapped the phrase 'delivery' to Late Delivery?" and the assistant will work through it with you.

Before you connect

Use the Thematic MCP first

Add the Thematic MCP server, sign in, and ask it something about your data — "what sources do we have?" is a good opener. Using it once is what establishes your region, and switching organization in it is what sets your organization. The Admin MCP reads both, and until they exist it has nothing to act on.

If you want to be certain before you start editing, ask the Thematic MCP which organization it is working in.

This is the one setup mistake that is hard to spot. Skip it and the Admin MCP still signs you in and still lists all 20 tools, so it looks connected — but every tool call comes back telling you to connect the Thematic MCP first, and nothing in the Admin MCP can fix it.

You can keep both connected, or remove the Thematic MCP afterwards; the Admin MCP keeps working either way. You need the Thematic MCP again only to move to a different organization or region.

You need theme editing rights

The built-in Dataset Administration role has theme editing rights for every survey and lens. Without them Thematic refuses every edit — ask whoever manages your Thematic users for the manage:themes  permission. See Permissions Glossary and Roles for how permissions and roles work.

Server URL

The Admin MCP is a remote MCP server over Streamable HTTP. Use the endpoint for your region — the same region as your Thematic MCP.

If you connect the Admin MCP at a different region from the one you are working in, it will tell you rather than fail silently.

Connecting your client

The Admin MCP connects exactly the same way as the Thematic MCP — only the server URL differs. Follow the instructions for your client in whichever of these applies:

1. OAuth using dynamic client registration — the simplest and most modern. Claude, Copilot, ChatGPT and Cursor all use this.
2. OAuth using explicit client registration — Gemini Enterprise requires this.
3. Bearer tokens — for when you can't authenticate in a browser and only have terminal access.

The Admin MCP and the Thematic MCP authorize separately, so you sign in to Thematic once for each.

Draft and live

Every change goes into a draft. A draft changes nothing your dashboards, reports or exports show.

   your edits  ──►  draft  ──►  apply_themes  ──►  live themes + full re-tag
                     ▲                                       │
                     └──────────  reset_draft  ◄─────────────┘

• Experiment freely. Until apply_themes , none of it is visible to anyone reading your dashboards.
• One draft per source, shared by your organization. It is not private to you — a colleague editing the same survey or lens is working on the same draft.
• Publishing is expensive. apply_themes  starts a full re-tag of the source's data. It runs in the background, takes a while, and is not easy to undo, so it requires an explicit confirmation.

This is the same draft that the Manage themes area uses, so a draft you build here is visible there and vice versa. Because applying themes changes analysis other people may already have seen, it is worth reading Theme discovery changing themes before your first publish.

The usual sequence

1. get_draft  to see the current themes; get_quality_score  and get_tagging_stats  to find where the problems are.
2. Run one of the AI checks for suggestions.
3. preview_phrase  on anything uncertain.
4. apply_transform  — the change lands in the draft, nothing is live yet.
5. diff_draft  to review the whole change.
6. apply_themes  to publish; get_apply_status  to follow the re-tag.

The two rules that matter

Preview single words before mapping them. A phrase matches on concept, not sentiment: map "service" and it tags "the service was excellent" and "the service was appalling" alike. That is fine for a theme named by topic ("Staff service") and wrong for one named by direction ("Unhelpful staff"). A bare single word on a directional theme is the usual cause of a theme that grows to cover everything. Ask for preview_phrase  and you see the split before you commit.

Review the diff before every publish. diff_draft  is the only place an unintended change shows up while it is still cheap to undo. Read the removed themes especially.

Everything in Theme editing best practices applies here too — what makes a good taxonomy, when to merge rather than delete, and why overly generic phrases cause trouble.

Available tools

You don't need to call these directly — just ask for what you want in conversation and the assistant will choose the right tools. The list is here so you know what is possible.

See what you have

Ask AI what to change

All of these are read-only. A suggestion normally arrives with the exact change attached, so applying it is one further step rather than fresh work — apart from the two-step case noted under Things that can look odd.

Two more work on a single theme and return phrases rather than a change:

• suggest_phrases_for_theme  works from a theme's title and existing phrases, so it suits a new or nearly empty theme.
• extract_phrases_from_comments  draws phrases from comments you name, which keeps them grounded in real wording. Comment ids come from get_comments  in the Thematic MCP.

discover_phrases  is the one to reach for once a theme set is already populated.

These are the same checks that power AI Suggestions in the Themes Editor. If you prefer to review suggestions as cards in the portal rather than in conversation, that is the same work in a different interface.

Check, then change

apply_transform  covers eight changes: AddTheme , ChangeThemeTitle , DeleteThemes  (cascading to sub-themes), MoveTheme , MergeTheme , UnmergeTheme , AddPhrases , DeletePhrases .

• Merge or delete? If a redundant theme's phrases are still catching useful comments, MergeTheme  keeps them working against the surviving theme. DeleteThemes  throws them away with the theme.
• Undoing a merge. UnmergeTheme  lifts out only the theme you name; anything folded in alongside it stays merged. Use restore_version  to undo a whole merge.

Publish and undo

restore_version  is the real undo: every version you apply is kept, so you can always bring back an earlier structure, review it, and publish it.

Things that can look odd

• preview_phrase  numbers are part exact, part sample. The response count is exact for the source you are working on; the sentence counts and examples come from a sample of up to 100 comments, with up to two examples per sentiment. It matches case-insensitively as a substring, so testing "service" also catches "services".
• get_tagging_stats  reads a sample of 200 comments. A sentence carrying three or more themes counts as crowded, and it reports the ten themes appearing most often on crowded sentences.
• suggest_phrases_for_theme  returns at most 25 phrases, and says so when there were more.
• Some suggestions take two steps. A suggestion that creates a theme and then targets that same theme cannot be applied in one go, because the new theme's id only exists once it has been created: the theme has to be created first, its id read back, and the rest applied against that id. Such a suggestion arrives with a note saying so.

Troubleshooting

If a theme tool behaves in a way this article does not explain, submit_feedback  in the Thematic MCP is where to report it — that tool lives on the read server, not this one.

Related articles

• Thematic MCP Server — the read server, and a prerequisite for this one
• Theme editing best practices — what a good theme taxonomy looks like
• Themes Editor - AI Suggestions — the same AI checks, in the portal
• How to edit themes in Manage themes area — the same draft, in the portal
• What are base and sub-themes? — the hierarchy these tools operate on