Management API & MCP

The Management API is the same REST API the dashboard itself uses, opened up with a token so your developers can script it. The MCP server exposes those same capabilities over the Model Context Protocol, so an AI assistant can configure a widget by conversation instead of you hunting through the builder.

Management tokens

Tokens are minted in Settings → API Keys → Management tokens, or via the API below. A token's scopes are the same permission strings your roles are built from — agents:edit, kb:create, help-centers:content — so there is no second permission system to learn.

Two rules that always hold

• A token can never exceed the person who created it. Scopes are intersected with the creator's live permissions on every request — not frozen at creation. Demote that person and their tokens are downgraded on the next call.
• A token can be pinned to specific widgets. Set agentIds and the token sees and edits only those widgets. Omit it for the whole organization.

Minting a token

curl -X POST "https://api.nextcap.ai/api/v1/management-tokens" \
  -H "Authorization: Bearer YOUR_DASHBOARD_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Widget setup for Acme",
    "preset": "widget-setup",
    "expiresInDays": 90
  }'

Requesting a scope you do not hold yourself is refused rather than quietly narrowed:

{
  "code": "SCOPE_EXCEEDS_CREATOR",
  "message": "A token cannot be given permissions you do not have yourself.",
  "permissions": ["billing:manage"]
}

Using the Management API

Every management endpoint accepts a token in place of a session. Paths, bodies and responses are identical — this is the same API the dashboard calls, not a parallel one. Covered surfaces include widgets, knowledge bases and documents, help centres and articles, departments, tickets, tags, quick replies, forms, conversations, leads, analytics, and the Telegram / WhatsApp / Instagram channels.

# List widgets
curl "https://api.nextcap.ai/api/v1/agents" \
  -H "Authorization: Bearer nextcap_mk_YOUR_TOKEN"

# Move the launcher up so it clears a cookie banner
curl -X PATCH "https://api.nextcap.ai/api/v1/agents/WIDGET_ID" \
  -H "Authorization: Bearer nextcap_mk_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "launcherOffsetY": 96 }'

Connecting an AI assistant (MCP)

The MCP endpoint is https://api.nextcap.ai/api/v1/mcp over Streamable HTTP, authenticated with the same token.

claude mcp add nextcap --transport http https://api.nextcap.ai/api/v1/mcp \
  --header "Authorization: Bearer nextcap_mk_YOUR_TOKEN"

Tools

Changes are previewed before they are written

update_widget runs as a dry run unless you explicitly pass dryRun: false. A dry run reads the current values, returns a field-by-field diff, and writes nothing.

{
  "applied": false,
  "note": "Nothing was written. Show this diff to the user, then call again with dryRun: false.",
  "changes": [
    { "field": "launcherOffsetY", "from": 20, "to": 96, "unchanged": false }
  ],
  "willChange": 1
}

Unknown field names are rejected with a suggestion rather than silently ignored:

Unknown setting(s): launcherOffset (did you mean "launcherOffsetY"?).
Use search_widget_settings to find the right field name.

Errors