Management MCP

The Management MCP server puts the Management API behind the Model Context Protocol, so an MCP client — Claude Code, Codex, Cursor, or anything that speaks streamable HTTP MCP — becomes a copilot for WizChat itself: you manage your chatbots in natural language instead of through hand-written HTTP calls.

You connect it once with a browser consent screen. There is no API key to create, copy, or paste.

• Endpoint: https://management-mcp.wizchat.com/api/mcp
• Transport: streamable HTTP
• Auth: OAuth 2.0 authorization code + PKCE (oat_… access tokens)
• Authorization server: https://www.wizchat.com

Not the same as the docs MCP

This is the control plane — it reads and changes your account's chatbots. The separate, public, read-only docs MCP at https://www.wizchat.com/api/docs-mcp only searches and reads these documentation pages. See Docs for AI Agents for that one. You can connect both at the same time; give them different names.

Connect

Claude Code

claude mcp add --transport http wizchat https://management-mcp.wizchat.com/api/mcp

Codex — register the server, then run the login command to authorize it:

codex mcp add wizchat --url https://management-mcp.wizchat.com/api/mcp
codex mcp login wizchat

codex mcp login opens the browser consent screen. Because this server requires authentication on every request, the connection stays empty until that login succeeds — run it before expecting any tools to appear. Confirm the result with codex mcp list.

You can also write the entry into ~/.codex/config.toml yourself:

[mcp_servers.wizchat]
url = "https://management-mcp.wizchat.com/api/mcp"
auth = "oauth"

note

Remote streamable-HTTP MCP servers are first-class in current Codex builds. On an older version that only picks up local command-based servers, upgrade Codex — that is simpler than enabling the experimental HTTP client by hand.

Cursor and other MCP clients — add an MCP server pointing at https://management-mcp.wizchat.com/api/mcp with the transport set to streamable HTTP. The same browser-consent flow applies.

Whichever client you use, authorizing opens a browser window where you sign in to WizChat and choose an access level. Once you approve, the client stores the resulting token and refreshes it automatically — you don't handle credentials yourself.

What happens during the connection

The server is a standards-compliant OAuth 2.0 protected resource, so a conformant MCP client bootstraps the whole flow on its own:

1. The client's first, unauthenticated request gets a 401 with a WWW-Authenticate header pointing at https://management-mcp.wizchat.com/.well-known/oauth-protected-resource (RFC 9728).
2. That document names the authorization server (https://www.wizchat.com) and the scopes the resource supports.
3. The client registers itself dynamically (RFC 7591) at POST /api/v1/oauth/register and receives a public dyn_… client id.
4. Your browser opens the consent screen at https://www.wizchat.com/oauth/authorize with a PKCE S256 challenge. You pick View or Manage and approve.
5. The client exchanges the returned code for an oat_… access token (about one hour) plus a rotating ort_… refresh token (about 30 days).

Tokens issued this way are bound to the Management MCP endpoint as their audience (RFC 8707), so a token minted for MCP cannot be replayed against a different resource. For your own server-to-server integrations, use the client-credentials flow instead.

What you can do

Once connected, the server exposes tools covering most of what the dashboard does. Your client lists the current set on connect — in Claude Code, run /mcp. The main groups:

Area	What the tools cover
Read	list_my_chatbots, get_chatbot_overview, get_chatbot_config, list_skills, list_mcp_servers, get_usage
Analytics	get_analytics — one chatbot, by category: usage, cost, conversations, queries, quality, search, infra, transcription, tokens. get_workspace_analytics for a cross-chatbot overview.
Models	list_models and compare_providers rank models and their infrastructure providers on live latency, throughput, price, and uptime; recommend_model picks one for a stated use case. Apply with change_ai_model.
Configuration	update_behavior (system prompt, temperature), update_appearance (display name, description, logo), welcome message, visibility, web search and unanswered-question tracking
Knowledge base	Ingest a PDF from a URL or upload a local PDF, CHM, or video via create_upload_url; add raw text or Markdown with ingest_text; crawl websites and schedule recurring re-crawls; list, read, and delete documents and videos; set per-document privacy
Knowledge scopes	create_scope, update_scope, delete_scope for single-scope edits; set_scopes for bulk structural changes; set_embedding_model
Skills and MCP servers	Create, read, edit, enable, disable, and remove skills; create and configure MCP servers on a chatbot, including their access keys
Sales agent	get_sales_agent, configure_sales_agent, set_sales_agent at full dashboard parity; manage existing lead-delivery channels; list, export, and DSAR-erase captured leads
Access and security	Email and domain allow-lists, embed origins, access protection, deployed end users, reusable email groups, telemetry privacy, the external Chat API and its keys
Chatbot lifecycle	Create a draft, provision and deploy it for the first time, re-deploy, and permanently delete — each confirm-gated
Custom domains	Add, verify, and remove a domain
Config-as-code	apply_config applies a whole config document, showing a dry-run plan first
Account	list_teams, list_team, list_connected_apps, revoke_connected_app
Authoring	generate_system_prompt, draft_welcome_message, suggest_improvements return suggested text only — nothing changes until you apply it

Refer to your chatbots by name. Every tool that takes a chatbotId also accepts a display name and resolves it, so you never need to look up an id.

A few things stay dashboard-only and are deliberately not exposed as tools: setting plaintext access-protection secrets, changing a chatbot's data region, creating knowledge bases, and creating a lead-delivery channel or setting its sending secret.

Confirming changes

Tools that write are confirm-gated. Calling one first returns a preview — its result opens with ⏳ and NOT APPLIED YET, and nothing has changed. Only a result opening with ✅ means the change was actually applied.

Inside the WizChat chat widget you approve by clicking Confirm in the dialog. Command-line clients can't render that dialog, so they apply a previewed change by calling the same tool again with identical arguments plus confirmed: true and the baseConfigHash value from the preview. The server detects those clients and explains this in its connection instructions.

warning

That re-call replaces the dialog click, not your decision. If the configuration changed since the preview, the server rejects the stale hash and applies nothing — preview again for a fresh one.

Access levels

The consent screen offers two tiers. The one you choose decides what the connected client can do for the whole grant.

Tier	What it grants
View	Read-only access to your chatbots, skills, MCP servers, domains, videos, knowledge-base documents, settings, and analytics.
Manage	Read + write across your chatbots, skills, MCP servers, domains, videos, and settings; read your knowledge-base documents and resolve transcript corrections.

Behind the tiers are the same scopes the rest of the Management API uses. The endpoint advertises the full set at https://management-mcp.wizchat.com/.well-known/oauth-protected-resource:

chatbots:read · chatbots:write · deploy · analytics:read · skills:read · skills:write · mcp:read · mcp:write · domains:read · domains:write · security:read · security:write · videos:read · videos:write · documents:read · documents:write

tip

Start with View. Connect again and choose Manage when you actually need the client to change something — a read-only grant cannot deploy, delete, or overwrite anything.

Review and revoke access

The consent screen shows two things you should check before approving: the exact client ID requesting access, and the origin the authorization code will be sent to. The client's display name is chosen by the client itself, so treat the redirect origin as the trustworthy signal.

To review what you have authorized, open the WizChat dashboard and go to Settings → API keys → Connected applications. Revoking a grant there immediately invalidates that client's tokens.

You can do the same programmatically with the owner-authenticated OAuth grants endpoints — GET /api/v1/oauth/grants and DELETE /api/v1/oauth/grants — described in the OAuth 2.0 guide.

Refresh tokens rotate on every use. If a rotated token is ever replayed, the entire token family is revoked and the client has to go through consent again.

Related

• OAuth 2.0 — the full credential model, including client credentials for server-to-server access.
• Management API overview — the endpoints behind these tools.
• Docs for AI Agents — the public, read-only documentation MCP server.