Connect an AI assistant

Hypervalent Studio ships a hosted Model Context Protocol server at https://mcp.hypervalent.io. Point Claude Desktop, Claude Code, Cursor — or any MCP client — at it and the assistant can read your content model, search and read documents, and (with read + write access) draft, edit and publish content in your projects.

There is nothing to install. There are two ways to connect: log in from the client (the quickest — no token to copy, below), or paste an API token (steps 1–2). Either way the server is stateless: every request carries a token and is forwarded to the public content API with exactly that token's permissions.

Plan

AI assistants are part of the Team plan and above. On other plans the panel in Studio shows an upgrade card, and the server answers every tool with an upgrade notice.

Connect by logging in

Add the server with just its URL — no token, no ?org=:

Claude Code

claude mcp add --transport http hypervalent https://mcp.hypervalent.io/mcp

Cursor — .cursor/mcp.json

{
  "mcpServers": {
    "hypervalent": { "url": "https://mcp.hypervalent.io/mcp" }
  }
}

In Claude (Settings → Connectors → Add custom connector) paste the same URL. The client shows Connect (or asks you to authenticate); a browser opens on Studio:

1. Sign in, if you are not already.
2. On Connect an app, pick the organization, optionally one project, and the access — Read only or Read and write.
3. Approve. The browser hands you back to the client, and the tools appear.

Only an organization admin can approve — the same people who can create API tokens. Anyone else sees "ask an organization admin to connect it". Read and write access needs a plan with API writes (Team and above).

The client receives a token that lasts an hour and renews itself in the background, so you are not asked again. The connection shows in Organization settings → API tokens as a Connected app; Revoke it there to disconnect — the next tool call fails and the client has to connect again.

Or paste a token

1. Create a token

In Studio go to Settings → API tokens → Create token.

• Scope: choose Read + write if the assistant should create or edit content. A read-only token connects fine, lists every tool, but every write is refused with TOKEN_SCOPE_READ_ONLY.
• Project: narrow the token to one project unless you really want the assistant to reach every project in the organization. A narrowed token never needs to be told which project to use.
• Expires: set one. Rotate the token from the same page when it lapses.

Copy the token when it is shown — it appears exactly once.

2. Copy the setup snippet

Open Settings → API tokens → Use with AI. The panel shows the server URL for your organization (https://mcp.hypervalent.io/mcp?org=<your org id>) and a snippet for each client. Pick the token you just created: the snippet shows its prefix (atk_xxxxxxxx…) so you know which one to paste — replace it with the full token.

Claude Desktop — claude_desktop_config.json

{
  "mcpServers": {
    "hypervalent": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.hypervalent.io/mcp?org=YOUR_ORG_ID",
        "--header", "Authorization: Bearer atk_YOUR_TOKEN"
      ]
    }
  }
}

Claude Code

claude mcp add --transport http hypervalent "https://mcp.hypervalent.io/mcp?org=YOUR_ORG_ID" \
  --header "Authorization: Bearer atk_YOUR_TOKEN"

Cursor — .cursor/mcp.json

{
  "mcpServers": {
    "hypervalent": {
      "url": "https://mcp.hypervalent.io/mcp?org=YOUR_ORG_ID",
      "headers": { "Authorization": "Bearer atk_YOUR_TOKEN" }
    }
  }
}

Restart the client (Claude Desktop needs a full restart — ⌘Q, not just the window). You should see the hypervalent server with its tools listed. Each client has its own page with the details and pitfalls: Claude Desktop · Claude Code · Cursor · other clients.

Why does Claude Desktop use mcp-remote?

Claude Desktop's config file launches local (stdio) servers only; a remote server added through its Connectors screen cannot send a custom Authorization header. The mcp-remote bridge runs locally (it needs Node.js) and forwards to the hosted server with your token. Claude Code and Cursor talk to the hosted URL directly.

Try it

Ask the assistant something like:

List the projects I can reach, then the document types in the site project.

Under the hood it calls list_projects, list_doctypes and get_doctype. The get_doctype answer is written for models: every field with its type, whether it is required, and the exact shape create_document expects — so "draft a new blog post about our launch" works without you explaining the content model.

Two prompts come built in (your client may show them as slash commands):

• draft-document — interviews you for each required field of a document type, shows a summary, then creates the draft. It never publishes on its own.
• content-audit — lists stale drafts and published documents missing a taxonomy term.

What it can do

Reads (any token)	Writes (read + write token)
List projects, document types, taxonomies, settings, design tokens	Create and edit documents and taxonomy terms (as drafts)
Read and search documents; read the draft (working) view	Publish and unpublish documents
Read a document type as an authoring schema	Trash documents
	Upload images from a URL or from data

The full list, with every argument, is in the tool reference.

What it cannot do

• Anything the token cannot: a project-narrowed token stays inside its project; a read-only token never writes; a revoked token fails on the next call.
• Reach the admin API. The server only forwards to the public content API — members, roles, billing and settings management are out of its reach entirely.
• Restore from the trash, manage media beyond uploading, or change structure (atoms, molecules, document types). Those stay in Studio.
• Search server-side: search_documents walks the document lists page by page, so keep searches narrow on large projects.

Safety

• Publishing is public. publish_document makes the document visible on the public API — and on every site that reads it — immediately. The tools are annotated so clients that honour them ask before destructive actions, and the built-in prompts never publish without being told. Say so in your instructions to the assistant if you want a confirmation step every time.
• Unpublish and trash are marked destructive. Unpublishing takes a document off the public API at once; publishing again restores it. Trash is restorable — a trashed document leaves the API and its slug is freed, but an editor can restore it from the trash in Studio. Nothing the assistant does deletes content permanently.
• Edits replace field values. When the assistant updates a document it sends the whole set of field values; the built-in guidance tells it to read the draft first. A document someone has open in the editor cannot be overwritten — the save is refused with the editor's name.
• Every write is attributed to the token in the organization's activity log, so you can see exactly what the assistant did and when.
• Revoke the token from Settings → API tokens to cut the assistant off instantly.

Troubleshooting

Symptom	Cause
The client says the server needs authentication	Expected when you added only the URL — choose Connect / log in. With a pasted token: the Authorization header is missing or not an atk_… token — check the snippet
The consent page says only an admin can connect	You are not an organization admin — ask one to connect the app (or to create a token for you)
A logged-in client suddenly asks to connect again	The connection was revoked in Studio (or not used for 30 days) — connect again
Every tool answers FEATURE_DISABLED / requires the Team plan	The organization's plan does not include AI assistants
Every tool answers INVALID_API_TOKEN	The token was revoked, expired, or belongs to a different organization than the org in the URL
Tools answer PROJECT_REQUIRED	The token is organization-wide; tell the assistant which project, or narrow the token
Writes answer TOKEN_SCOPE_READ_ONLY	Create a read + write token
A save answers VERSION_LOCKED	Someone has the document open in the editor; try again after they close it

More: AI assistants overview · Tokens & permissions · Authoring content · Errors & limits · Troubleshooting

Related: Pricing · AI assistants on hypervalent.io