Tools Reference

This guide documents the tools available in the Chipp MCP Server, organized by category.

Quick Reference

Jump to a category or use this table to find tools quickly:

Related APIs: the MCP server is one of three programmatic surfaces. The Builder API is a REST API using per-app chipp_ keys (sessions, consumers, conversation logging over HTTP), and the Org Export API uses org-wide chipp_org_ keys for bulk transcript export. MCP tokens (chipp_sk_ / OAuth) are organization-scoped and cover the full tool surface below.

Apps

Core CRUD operations for managing Chipp applications.

list_apps

List all applications accessible to the authenticated user.

Scope: apps:read. Chipp MCP: core

Example:

"List all my Chipp apps"
"Show apps in workspace 42"

get_app

Get detailed information about a specific application.

Scope: apps:read. Chipp MCP: core

Example:

"Get details for app 123"
"Show me the configuration of my FAQ bot"

create_app

Create a new application in a workspace.

Scope: apps:write. Chipp MCP: apps

Example:

"Create a customer support bot called HelpDesk in workspace 5"
"Make a new app named FAQ Bot with a helpful assistant prompt"

update_app

Update an app’s settings. settings takes the same fields the Chipp Alchemist uses: name, display_name, description, instructions (the system prompt), model, temperature, capabilities, brand styles and colors, voice, auth mode, email gating, language, custom CSS, starter messages, uploads, spending limit and more. The fields you send are merged into the current config; the rest are kept.

Scope: apps:write. Chipp MCP: app-settings

Each field needs the matching workspace permission, as in the dashboard (for example, a theme needs Branding and a name needs App Settings); the spending limit needs App Settings and a plan with spending limits.

instructions, welcomeMessage, greetingPrompt and customCss replace the whole value: read the current value first (get_system_prompt, get_settings) and keep what should stay.

ragConfig tunes knowledge retrieval: maxResults (1-25, default 5), minScore (0-1, default 0.15), vectorWeight (0-1, default 0.7), textWeight (0-1, default 0.3), useDocumentBoosting (default true) and documentWeight (0-1, default 0.3). Only the keys you send change. An unknown key or an out-of-range value is refused. It takes effect after the app is re-published. See RAG Settings.

The earlier flat parameters name, display_name, description and is_public still work.

Returns success, the updated field list and a message; after an instructions change, instructionsLength and instructionsPreview show what was stored. A refused payload returns success: false and an error naming the fix (for example, a [component:Name] placeholder, or custom CSS that tries to hide the microphone button, which has its own toggle).

Example:

"Rename app 123 to 'Support Bot v2'"
"Turn on web search and switch my FAQ app to the classic-chipp theme"

bulk_update_app_settings

Apply the same settings to many apps in one call (up to 200), for example a theme on every app in a workspace. Each app is written on its own: an app you cannot reach, or that fails, is listed in failed and never blocks the others.

Scope: apps:write. Chipp MCP: app-settings

Each app needs the same per-field workspace permissions as update_app.

Returns success (true only when every app was updated), total, succeeded, failed ({ appId, error } for each app not updated; an app you cannot reach reads “not found or no access”), updatedFields and a message. Retry with only the failed ids.

Example:

"Set the classic-chipp theme on every app in my Support workspace"

get_app_settings_help

The guidance for app settings fields: what each one does, its default, when to use it, and what it is not for. Read it before you change a field such as capabilities.memory, trialMode, sessionTerminationEnabled, ragConfig or customCss with update_app or bulk_update_app_settings. It reads no app data.

Scope: apps:read. Chipp MCP: app-settings

Returns fields (the guidance text for each path) and unknown (paths that have no guidance).

Example:

"What does session termination do before I turn it on?"

delete_app

Soft-delete an application.

Scope: apps:write. Chipp MCP: apps

Example:

"Delete app 123"
"Remove the test app I created"

chat_with_app

Send a message to an application and get a response. Useful for testing.

Scope: apps:read. Chipp MCP: apps

Example:

"Test my FAQ bot with the question 'What are your hours?'"
"Send 'hello' to app 123 to check if it's working"

Response shape:

{
  "response": "The assistant's reply text (may be empty if only a UI component rendered).",
  "session_id": "uuid",
  "model": "claude-sonnet-4-6",
  "component_invocations": [
    {
      "component_id": "uuid",
      "component_name": "PricingTable",
      "props": { "tier": "STUDIO_PRO" },
      "tool_call_id": "call_abc"
    }
  ],
  "usage": { "input_tokens": 1234, "output_tokens": 567 }
}

component_invocations lists every custom UI component the app rendered during the turn (render_<snake_name> tool calls). The array is always present, empty when no components rendered. Use this when your app uses Component Studio and you need to see what rendered (the response text is often empty for component-rendering turns).

search_apps

Search apps by name or description across the workspaces you can reach. An API key searches its own organization unless all_orgs is true.

Scope: apps:read. Chipp MCP: core

Returns apps (each with its slug, workspace and organization), count, the query, your current_workspace_id and current_organization_id, and a hint. A UUID never matches app text, so a UUID query is refused with a pointer to get_app.

publish_app

Publish the current app configuration to make it live for consumers. Creates a version snapshot and deploys it.

Scope: apps:write. Chipp MCP: apps

Returns: version_id, already_published flag, and the tag used.

list_app_versions

List published version history for an app.

Scope: apps:read. Chipp MCP: apps

duplicate_app

Create a copy of an existing app with all its configuration, system prompt, and settings.

Scope: apps:write. Chipp MCP: apps

restore_app_version

Restore an app’s configuration to a previous version. Does not publish: use publish_app afterward if needed.

Scope: apps:write. Chipp MCP: apps

rollback_app_version

Rollback an app to a previously published version and immediately publish it. Combines restore + publish in one step.

Scope: apps:write. Chipp MCP: apps

get_app_url

Get the consumer-facing URL for an app (custom domain, vanity subdomain, or default path). Also returns the embed widget snippet.

Scope: apps:read. Chipp MCP: core

Returns: consumer_url, default_url, has_custom_domain, and embed_snippet.

update_app_slug

Change an app’s URL slug (the short identifier in the consumer chat URL, e.g. my-sales-bot).

Scope: apps:write. Chipp MCP: apps

Configuration

Manage application settings, system prompts, and branding.

get_system_prompt

Get the system prompt for an application.

Scope: apps:read. Chipp MCP: apps

update_system_prompt

Update an application’s system prompt.

Scope: apps:write. Chipp MCP: apps

get_model

Get the AI model configuration for an application.

Scope: apps:read. Chipp MCP: apps

update_model

Change the AI model and/or temperature for an application.

Scope: apps:write. Chipp MCP: apps

get_settings

Get detailed settings including RAG configuration.

Scope: apps:read. Chipp MCP: app-settings

update_settings

Update application settings, capabilities, welcome messages, and suggested starters.

Scope: apps:write. Chipp MCP: app-settings

Top-level settings keys are shallow-merged. settings.ragConfig is the exception: it is validated and merged key by key, so sending {"ragConfig": {"minScore": 0.25}} keeps every other retrieval setting. It takes maxResults (1-25), minScore, vectorWeight, textWeight and documentWeight (each 0-1), useDocumentBoosting, plus the full-document keys fullDocumentMode, fullDocumentMaxPages (1-600) and fullDocumentCacheTtl ("5m" or "1h"). An unknown key or an out-of-range value fails the call and nothing is written. "ragConfig": null clears every retrieval setting back to the defaults. Changes take effect after re-publish. See RAG Settings.

update_branding

Update visual branding for the application.

Scope: apps:write. Chipp MCP: app-settings

list_suggestions

Get the suggested conversation starters shown to users on the chat interface.

Scope: apps:read. Chipp MCP: apps

update_suggestions

Set the suggested conversation starters shown to users. Pass an empty array to clear all suggestions.

Scope: apps:write. Chipp MCP: apps

Example:

"Set the starter prompts for my support bot to: 'Track my order', 'Return an item', 'Speak to a human'"

update_auth

Update an app’s consumer authentication settings. All fields are optional and live-on-save (no re-publish needed).

Scope: apps:write. Chipp MCP: app-settings

set_tool_override

Toggle enable/disable or update the LLM-facing description for a single tool override on an app.

Scope: apps:write. Chipp MCP: app-settings

list_tool_keys

List every valid tool_key for an app: built-in tools, hosted-integration tools, custom component tools (render_*), custom action tools, and MCP integration tools.

Scope: apps:read. Chipp MCP: app-settings

get_default_capabilities

Get the canonical platform-default state for capabilities, settings, and tool overrides. Takes no parameters.

Scope: apps:read. Chipp MCP: app-settings

No parameters.

Knowledge Sources

Manage RAG (Retrieval-Augmented Generation) knowledge bases.

list_knowledge_sources

List all knowledge sources for an application.

Scope: knowledge:read. Chipp MCP: knowledge

get_knowledge_source

Get details about a specific knowledge source.

Scope: knowledge:read. Chipp MCP: knowledge

add_url_source

Add a URL as a knowledge source. Automatically detects YouTube, Instagram, TikTok, and regular web pages.

Scope: knowledge:write. Chipp MCP: knowledge

Example:

"Add https://docs.example.com to my FAQ app and crawl 3 levels deep"
"Add this YouTube video to my training bot's knowledge base"

add_text_source

Add raw text content as a knowledge source.

Scope: knowledge:write. Chipp MCP: knowledge

Example:

"Add this FAQ text to my support bot's knowledge base"

delete_knowledge_source

Remove a knowledge source from an application.

Scope: knowledge:write. Chipp MCP: knowledge

refresh_knowledge_source

Re-crawl or re-process a knowledge source to update its content.

Scope: knowledge:write. Chipp MCP: knowledge

list_active_crawls

List knowledge sources currently being processed or queued for an app.

Scope: knowledge:read. Chipp MCP: knowledge

Returns: Active processing jobs with job type, status, attempt counts, and the source name/URL being processed.

cancel_crawl

Cancel all pending and in-progress processing jobs for a knowledge source.

Scope: knowledge:write. Chipp MCP: knowledge

The source status is set to failed. Jobs that are already running on a worker may complete, but no new queued jobs will start.

add_document_source

Upload one or more document files as knowledge sources. Files are provided as base64-encoded content.

Scope: knowledge:write. Chipp MCP: knowledge

Supported formats: PDF, DOCX, TXT, MD, CSV, JSON, XLSX, XLS, and audio files (MP3, WAV, M4A, etc.).

Each file object requires fileName (with extension) and content (base64-encoded).

get_crawl_progress

Get the processing progress for a knowledge source: current status, chunk count, pages completed, and any error messages.

Scope: knowledge:read. Chipp MCP: knowledge

link_knowledge_source

Link a knowledge source from one app to another, sharing its RAG data without duplicating it.

Scope: knowledge:write. Chipp MCP: knowledge

unlink_knowledge_source

Remove a linked knowledge source from an app. Does not delete the original source.

Scope: knowledge:write. Chipp MCP: knowledge

list_linked_knowledge_sources

List knowledge sources linked to an app from other apps (shared sources).

Scope: knowledge:read. Chipp MCP: knowledge

Enterprise KB Evidence

Read-only evidence retrieval over the org/workspace-scoped enterprise knowledge base. Authorization is resolved live on every call, so a revoked grant or a narrowed sharing scope takes effect immediately. Denials are uniform: a source that does not exist and one you are not authorized for return the same response, so nothing leaks about the wider corpus.

These are distinct from the Knowledge Sources tools above, which manage an app’s OWN sources. Here app_id names the app acting as the retrieval caller, and you must already have access to it.

discover_kb_capabilities

List which org/workspace-scoped KB sources this app is currently granted access to. Always live, never a cached snapshot.

Scope: knowledge:read. Chipp MCP: knowledge

search_kb_evidence

Run a bounded, paginated hybrid search (vector similarity + BM25 + document boosting) across the granted KB sources. Every hit carries a citation (source id + chunk anchor) that get_kb_cited_chunk resolves to exact content.

Scope: knowledge:read. Chipp MCP: knowledge

get_kb_source_metadata

Get sanitized metadata (display name, sanitized url, type, sharing scope) for one granted source. Storage credentials and signed URLs are never returned.

Scope: knowledge:read. Chipp MCP: knowledge

get_kb_cited_chunk

Resolve one search citation to its exact chunk content. Authorization is re-checked at read time, so a chunk cited by an earlier search is denied if the grant has since been revoked.

Scope: knowledge:read. Chipp MCP: knowledge

read_kb_full_document

Read the full content of one granted source. Gated by the same policy as search and metadata; there is no separate, weaker full-document grant.

Scope: knowledge:read. Chipp MCP: knowledge

Analytics

Access usage data, conversations, and metrics.

Access usage data, conversations, and metrics.

get_app_analytics

Get summary analytics for an application: total sessions, messages, unique users, and date range stats.

Scope: analytics:read. Chipp MCP: analytics

Returns: Total sessions, messages, unique users, first and last session timestamps.

search_conversations

Search conversations with filters.

Scope: analytics:read. Chipp MCP: analytics

Example:

"Find conversations about refunds in my support bot"
"Show recent conversations from the last week"

get_conversation

Get a specific conversation with all messages.

Scope: analytics:read. Chipp MCP: analytics

get_top_queries

Get the most common user queries.

Scope: analytics:read. Chipp MCP: analytics

get_model_usage

Get LLM model usage breakdown (token counts by model) for an app.

Scope: analytics:read. Chipp MCP: analytics

get_response_time_analytics

Get response time statistics based on message timestamps.

Scope: analytics:read. Chipp MCP: analytics

Returns: Total responses, avg response ms, p50, p95.

get_user_engagement

Get user engagement metrics: sessions per user, messages per session, return rate.

Scope: analytics:read. Chipp MCP: analytics

search_messages

Search for specific text within messages across all conversations in an app.

Scope: analytics:read. Chipp MCP: analytics

Returns matching messages with a 500-character content preview and session context.

search_documentation

Full-text search within an app’s knowledge base (RAG chunks).

Scope: knowledge:read. Chipp MCP: analytics

Useful for checking what content is indexed before a chat, or debugging RAG retrieval issues.

get_tag_analytics

Get tag usage statistics for an app over a time period.

Scope: analytics:read. Chipp MCP: analytics

Returns: Per-tag counts for total fires, active fires, removed fires, text-replaced count, avg similarity, and last fired timestamp.

get_file_analytics

Get file upload statistics for an app: upload counts and total storage by MIME type.

Scope: analytics:read. Chipp MCP: analytics

Returns: Breakdown for both chat session uploads and consumer brain files.

get_moderation_stats

Get moderation statistics: how many conversations were frozen, had responses replaced, or triggered notifications.

Scope: analytics:read. Chipp MCP: analytics

Returns: Tag fire counts broken down by action type (freeze, static text, notification, webhook, manually removed) and affected session count.

get_popular_apps

Get the most-used apps in your organization, ranked by session count and unique users.

Scope: analytics:read. Chipp MCP: analytics

export_conversations

Export conversations as JSON for an app within a date range.

Scope: analytics:read. Chipp MCP: analytics

Tags

Manage intent tags for message classification and automated responses.

list_tags

List all tags for an application.

Scope: apps:read. Chipp MCP: tags

get_tag

Get details for a specific tag including utterances.

Scope: apps:read. Chipp MCP: tags

create_tag

Create a new intent tag.

Scope: apps:write. Chipp MCP: tags

Actions when the tag matches:

• static_text: Replace AI response with fixed text
• freeze_conversation: Stop conversation flow
• notification_enabled with notification_email or webhook_url: Send an email or webhook alert

Example:

"Create a tag called 'pricing' for my sales bot with examples like 'how much does it cost'"

update_tag

Update an existing tag.

Scope: apps:write. Chipp MCP: tags

delete_tag

Delete a tag.

Scope: apps:write. Chipp MCP: tags

list_tag_instances

List messages that matched a specific tag.

Scope: analytics:read. Chipp MCP: tags

remove_tag_instance

Soft-delete a specific tag detection instance from a message. The instance is marked as removed rather than permanently deleted.

Scope: apps:write. Chipp MCP: tags

generate_utterances

Generate training utterances for a tag using AI. Utterances are example phrases that should trigger the tag, and more utterances means better detection accuracy.

Scope: apps:write. Chipp MCP: tags

Example:

"Generate 30 training utterances for a tag called 'pricing question' that detects when users ask about cost"

set_tag_examples

Replace a tag’s positive and/or negative example utterances without touching its other config.

Scope: apps:write. Chipp MCP: tags

add_tag_examples

Append positive and/or negative example utterances to an existing tag without touching its other config.

Scope: apps:write. Chipp MCP: tags

Tag Examples

Fine-grained management of individual training utterances (examples) attached to a tag. For whole-set replace/append operations, see set_tag_examples and add_tag_examples.

list_tag_examples

List positive and negative examples (training utterances) for a tag.

Scope: apps:read. Chipp MCP: tags

create_tag_examples

Create (attach) one or more examples for a tag, all sharing the same polarity. Duplicate text for the tag is skipped and counted, not errored.

Scope: apps:write. Chipp MCP: tags

update_tag_example

Update an existing tag example’s text and/or polarity.

Scope: apps:write. Chipp MCP: tags

delete_tag_example

Delete (detach) a tag example.

Scope: apps:write. Chipp MCP: tags

import_tag_examples

Bulk-import tag examples from CSV or JSONL. CSV needs a header row with a required utterance column plus optional type (positive|negative, default positive) and source columns. JSONL is one JSON object per line: {utterance, type?, source?}. Duplicate text (either polarity) is skipped and counted, not errored.

Scope: apps:write. Chipp MCP: tags

Evaluations

Create and run quality tests for your applications.

list_evals

List all evaluations for an application.

Scope: apps:read. Chipp MCP: analytics

get_eval

Get details for a specific evaluation.

Scope: apps:read. Chipp MCP: analytics

create_eval

Create a new evaluation with test cases for an app.

Scope: apps:write. Chipp MCP: analytics

Test case format:

{
  "input": "What are your hours?",
  "expected_output": "We're open 9-5 Monday through Friday"
}

update_eval

Update an existing evaluation’s name, test cases, or method.

Scope: apps:write. Chipp MCP: analytics

delete_eval

Delete an evaluation.

Scope: apps:write. Chipp MCP: analytics

run_eval

Run an evaluation against the app to score its responses on the test cases.

Scope: apps:write. Chipp MCP: analytics

list_eval_results

List past evaluation runs.

Scope: apps:read. Chipp MCP: analytics

get_eval_result

Get detailed results from a specific evaluation run.

Scope: apps:read. Chipp MCP: analytics

Custom Actions

Manage API integrations for your applications.

list_custom_actions

List all custom actions for an application.

Scope: actions:read. Chipp MCP: actions

get_custom_action

Get the full current row of a custom action: url, method, headers, query_params, body_params, path_params, variables and auth, plus a hint.

Scope: actions:read. Chipp MCP: actions

The arrays use the names update_custom_action takes, so you can pass them back unchanged.

create_custom_action

Create a new API integration.

Scope: actions:write. Chipp MCP: actions

update_custom_action

Update an existing custom action.

Scope: actions:write. Chipp MCP: actions

It also needs write access to Custom Actions in the app’s workspace.

headers and the three params arrays replace the stored lists: call get_custom_action first and send back every entry you want to keep. A URL that belongs to a first-party hosted integration is refused with a hint to connect that integration instead. Returns the updated action with success, the updated field list and a message.

delete_custom_action

Delete a custom action.

Scope: actions:write. Chipp MCP: actions

test_custom_action

Test a custom action by executing it with sample parameters.

Scope: actions:write. Chipp MCP: actions

MCP Integrations

Connect external MCP servers to your applications.

list_mcp_integrations

List all connected MCP servers for an application.

Scope: actions:read. Chipp MCP: integrations

get_mcp_integration

Get details about a connected MCP server.

Scope: actions:read. Chipp MCP: integrations

connect_mcp_server

Connect an external MCP server to an application.

Scope: actions:write. Chipp MCP: integrations

update_mcp_integration_tools

Enable or disable the entire MCP integration, or toggle specific tools by name.

Scope: actions:write. Chipp MCP: integrations

disconnect_mcp_server

Remove an MCP server connection.

Scope: actions:write. Chipp MCP: integrations

list_hosted_integrations

List hosted integration providers connected to an app (Google Drive, Gmail, Outlook, OneDrive, Slack, and others).

Scope: apps:read. Chipp MCP: integrations

Returns: For each integration: provider, label, is_active, account_email, and requires_consumer_auth.

Components

Manage Component Studio custom UI components: HTML fragments (with embedded <style>/<script>) rendered in a sandboxed iframe inside the consumer chat via render_<name> tools.

list_components

List custom UI components for an app. Returns owned components first, then components linked via sharing. Each component includes its full source code and the render_tool_name the chat LLM calls to render it.

Scope: components:read. Chipp MCP: actions

get_component

Get a single component by ID, including its full source code and render_tool_name. Always call this before update_component: never refine a component from page context alone.

Scope: components:read. Chipp MCP: actions

create_component

Create a custom UI component owned by an app. The code is an HTML fragment with embedded <style> and <script> that runs in a sandboxed iframe. Dangerous patterns (fetch, eval, external scripts, localStorage) are rejected.

Scope: components:write. Chipp MCP: actions

update_component

Update an existing component. Call get_component first to read the full current code. name, code, and props_schema are all optional; only supplied fields change.

Scope: components:write. Chipp MCP: actions

delete_component

Delete a component. Idempotent: deleting an already-deleted component returns already_deleted: true. Also removes all links referencing the component.

Scope: components:write. Chipp MCP: actions

copy_component

Copy a component into another app as an independent copy (edits never propagate back to the source). The new copy starts with sharing_scope=PRIVATE.

Scope: components:write. Chipp MCP: actions

link_component

Link a shared component to another application. The source must have sharing_scope=WORKSPACE or ORGANIZATION, and the target app must be in the same scope.

Scope: components:write. Chipp MCP: actions

unlink_component

Unlink a shared component from an application. Idempotent: unlinking a non-existent link returns already_unlinked: true.

Scope: components:write. Chipp MCP: actions

update_component_sharing

Update a component’s sharing scope. PRIVATE is always allowed; WORKSPACE requires the shared-components capability (BUILDER+); ORGANIZATION requires the org-components capability (STUDIO+). Narrowing the scope cleans up now-out-of-scope links.

Scope: components:write. Chipp MCP: actions

list_available_shared_components

List shared components available for linking to an app: WORKSPACE-scoped components from the same workspace, plus ORGANIZATION-scoped components when the org-components capability is active.

Scope: components:read. Chipp MCP: actions

list_linked_components

List components currently linked to an app (owned by another app, shared into this one). For owned + linked together, use list_components.

Scope: components:read. Chipp MCP: actions

Deployments

Manage multi-channel deployments (Slack, WhatsApp, Email, Voice).

list_slack_deployments

List Slack integrations across all apps in your organization. Takes no parameters.

Scope: apps:read. Chipp MCP: channels

No parameters.

get_slack_deployment

Get the Slack integration config for an app.

Scope: apps:read. Chipp MCP: channels

list_slack_installations

List available Slack workspaces that have been connected to any app in your organization. Takes no parameters.

Scope: apps:read. Chipp MCP: channels

No parameters.

connect_slack_deployment

Connect an app to a Slack workspace.

Scope: apps:write. Chipp MCP: channels

disconnect_slack_deployment

Remove the Slack connection from an app.

Scope: apps:write. Chipp MCP: channels

get_whatsapp_deployment

Get WhatsApp business configuration.

Scope: apps:read. Chipp MCP: channels

get_voice_config

Get voice agent configuration.

Scope: apps:read. Chipp MCP: channels

update_voice_config

Update voice agent settings.

Scope: apps:write. Chipp MCP: channels

get_email_deployment

Get email channel configuration.

Scope: apps:read. Chipp MCP: channels

update_email_deployment

Update email channel settings.

Scope: apps:write. Chipp MCP: channels

get_discord_deployment

Get the Discord bot integration status for an app.

Scope: apps:read. Chipp MCP: channels

Returns: connected, discord_app_id, is_active, and connection timestamp.

get_github_deployment

Get the GitHub App integration status for an app (auto-respond to issues and PRs).

Scope: apps:read. Chipp MCP: channels

Returns: connected, account_login, auto_respond_issues, and installation details.

Consumers

Manage end-users (consumers) of your applications.

list_consumers

List consumers of an app with search and filtering.

Scope: analytics:read. Chipp MCP: analytics

get_consumer

Get details about a specific consumer including their session count.

Scope: analytics:read. Chipp MCP: analytics

update_consumer

Update a consumer’s credit balance or subscription status.

Scope: apps:write. Chipp MCP: analytics

get_user_memories

Get the AI memories stored for a specific consumer: facts and context the AI has learned across conversations.

Scope: analytics:read. Chipp MCP: analytics

Only active (non-superseded) memories are returned.

Workspaces

Manage workspaces and team members.

list_workspaces

List all workspaces you have access to.

Scope: workspace:read. Chipp MCP: core

get_workspace

Get details about a specific workspace.

Scope: workspace:read. Chipp MCP: core

list_workspace_members

List members of a workspace.

Scope: workspace:read. Chipp MCP: core

create_workspace

Create a new workspace in your organization.

Scope: workspace:write. Chipp MCP: core

Example:

"Create a new workspace called Marketing"

Billing

View subscription and credit information.

get_subscription

Get subscription details for an organization.

Scope: billing:read. Chipp MCP: billing

No parameters.

get_credits

Get credit balance and usage.

Scope: billing:read. Chipp MCP: billing

No parameters.

get_usage

Get LLM token usage and non-LLM usage events for the organization.

Scope: billing:read. Chipp MCP: billing

Returns: token_usage — one row per model, with:

Plus usage_events (non-LLM usage: document parsing, etc.) with usage_type, event_count, total_quantity.

Breaking change (CHIPPD-1437): the old total_input_tokens field (which counted ordinary input tokens only) has been removed, not renamed. Anthropic prompt-caching tokens (cache_read_input_tokens / cache_creation_input_tokens) are DISJOINT from input_tokens, not a subset — for cache-heavy apps they can be 100-500x the ordinary input count. Silently folding them into total_input_tokens risked double counting for any client already summing components client-side. If your integration read total_input_tokens, switch to total_effective_input_tokens (the full picture) or input_tokens (ordinary-only, matching the old field’s actual semantics).

Worked example (mirrors a real cache-dominant app): a model with input_tokens: 51374, cache_read_input_tokens: 29000000, cache_creation_input_tokens: 838515 has total_effective_input_tokens: 29889889 — cache accounts for ~99.8% of real input volume. Reading input_tokens alone would under-report by ~580x.

get_usage_by_app

Get token usage broken down by app for the organization.

Scope: billing:read. Chipp MCP: billing

Returns: app_breakdown — one row per app, with application_id, app_name, call_count, and the SAME input-token breakdown as get_usage above: input_tokens, cache_read_input_tokens, cache_creation_input_tokens, total_effective_input_tokens, total_output_tokens. See get_usage’s breaking-change note — total_input_tokens was removed here too, for the same reason.

get_capabilities

Get a boolean map of all feature capabilities for the organization: what features are available based on tier, add-ons, and feature flags.

Scope: billing:read. Chipp MCP: billing

No parameters.

Prompt Engineering

AI-assisted tools for improving prompts and selecting models.

list_available_models

List all AI models available for use.

Scope: apps:read. Chipp MCP: apps

No parameters.

generate_system_prompt

Generate a new system prompt from a description.

Scope: apps:write. Chipp MCP: apps

improve_system_prompt

Use AI to analyze and improve an existing system prompt.

Scope: apps:write. Chipp MCP: apps

recommend_model

Get AI-powered model recommendations for your use case.

Scope: apps:read. Chipp MCP: apps

generate_suggestions

Generate conversation starter suggestions for an app based on its system prompt. These are the suggested messages shown to users to begin a conversation.

Scope: apps:read. Chipp MCP: apps

Example:

"Generate 6 starter suggestions for my customer support bot"

Action Collections

Manage reusable action bundles that can be linked to multiple applications.

list_action_collections

List action collections owned by you or shared within your organization.

Scope: actions:read. Chipp MCP: actions

get_action_collection

Get details for a specific action collection.

Scope: actions:read. Chipp MCP: actions

create_action_collection

Create a new action collection.

Scope: actions:write. Chipp MCP: actions

update_action_collection

Update an action collection’s name or description.

Scope: actions:write. Chipp MCP: actions

delete_action_collection

Delete an action collection. Also removes it from any linked apps.

Scope: actions:write. Chipp MCP: actions

link_collection_to_app

Link an action collection to an application, making its actions available.

Scope: actions:write. Chipp MCP: actions

unlink_collection_from_app

Remove an action collection from an application.

Scope: actions:write. Chipp MCP: actions

list_linked_collections

List all action collections linked to a specific application.

Scope: actions:read. Chipp MCP: actions

update_collection_sharing

Update the sharing scope of an action collection.

Scope: actions:write. Chipp MCP: actions

• PRIVATE: only you can see it
• WORKSPACE: anyone in your workspace can discover and link it
• PUBLIC: visible in the marketplace

import_collection_tools

Import tools from an action collection into an app as standalone custom actions. Unlike link_collection_to_app, imported tools are independent copies you can modify freely without affecting the source collection.

Scope: actions:write. Chipp MCP: actions

Returns: Count of imported tools and any that were skipped due to slug conflicts.

Variables

Manage application variables (key-value configuration used by custom actions).

list_app_variables

List all variables for an application.

Scope: apps:read. Chipp MCP: apps

get_app_variable

Get details for a specific application variable.

Scope: apps:read. Chipp MCP: apps

create_app_variable

Create a new application variable.

Scope: apps:write. Chipp MCP: apps

update_app_variable

Update an application variable’s value, label, or description.

Scope: apps:write. Chipp MCP: apps

delete_app_variable

Delete an application variable.

Scope: apps:write. Chipp MCP: apps

Heartbeat

Configure and monitor proactive messaging (heartbeat): your app reaching out to consumers on a schedule.

get_heartbeat_config

Get the heartbeat configuration for an app.

Scope: apps:read. Chipp MCP: channels

Returns: heartbeat_config (enabled, every, prompt, targets, schedules, and the rest), plus the diagnostics that explain delivery: tierInfo, freeQuota, channelReadiness, broadcastRecipients, consumerEligibility (who is eligible now and why others are skipped; there is no consumer opt-in step), receiptFiling, deliveryHealth per schedule, recentRuns, and taskCredentialReadiness when a schedule runs as a background task.

update_heartbeat_config

Update heartbeat configuration. Set the interval, prompt, delivery channels, and model.

Scope: apps:write. Chipp MCP: channels

list_heartbeat_runs

List recent heartbeat runs for an app. Shows which consumers were contacted and outcomes.

Scope: analytics:read. Chipp MCP: channels

trigger_heartbeat

Manually trigger a heartbeat run for an app.

Scope: apps:write. Chipp MCP: channels

Agent Links

Link agents (apps) together so one app can call another as a tool during chat.

list_agent_links

List agents linked to an app.

Scope: apps:read. Chipp MCP: apps

list_available_agents

List agents available to link to an app (apps in the same organization not already linked).

Scope: apps:read. Chipp MCP: apps

link_agent

Link another agent (app) to this app so it can be called as a tool during chat.

Scope: apps:write. Chipp MCP: apps

Example:

"Link the 'Booking Agent' app to my 'Customer Support' app"

unlink_agent

Remove an agent link from an app.

Scope: apps:write. Chipp MCP: apps

App Agents

An app can hold several user-facing agents. End users pick one in the chat, and each agent has its own instructions, allowed tools, and display settings. Every agent has a stable agent_id: tools change an agent by that id, never by its name. The default agent serves app links, embeds, and channels that name no agent.

list_app_agents

List the agents inside an app, with their stable ids.

Scope: apps:read. Chipp MCP: apps

sync_app_agent

Create an agent (omit agent_id) or update exactly one agent (pass its agent_id). Other agents are never changed. Creating with a name that is already taken returns the existing agent with already_exists: true and changes nothing.

Scope: apps:write. Chipp MCP: apps

Database Connections

Manage external database connections attached to apps. Supported types: postgres, mysql, mssql, bigquery, snowflake, clickhouse.

list_database_connections

List external database connections for an app.

Scope: apps:read. Chipp MCP: actions

get_database_connection

Get details about a database connection.

Scope: apps:read. Chipp MCP: actions

create_database_connection

Create a new external database connection for an app. Connection strings are encrypted at rest.

Scope: apps:write. Chipp MCP: actions

delete_database_connection

Delete a database connection from an app.

Scope: apps:write. Chipp MCP: actions

test_database_connection

Test a database connection and discover its schema (tables, columns, types).

Scope: apps:write. Chipp MCP: actions

Monetization

Manage credit packages that consumers can purchase within your app.

list_consumer_packages

List credit packages available for consumers to purchase in an app.

Scope: apps:read. Chipp MCP: billing

create_consumer_package

Create a new credit package for consumer purchase. Supports one-time and subscription packages.

Scope: apps:write. Chipp MCP: billing

update_consumer_package

Update a consumer credit package.

Scope: apps:write. Chipp MCP: billing

delete_consumer_package

Delete a consumer credit package (soft delete).

Scope: apps:write. Chipp MCP: billing

get_monetization_stats

Get monetization analytics for an app: total revenue, purchases, active subscriptions, and unique customers.

Scope: analytics:read. Chipp MCP: billing

Conversation Logging

log_chat_message

Log a user message and/or AI response into a Chipp app’s chat history so it appears in the Conversations dashboard, analytics, and tag detection. Useful when the actual conversation happens outside Chipp (your own backend, a custom channel). The Builder API offers the same capability over REST.

Scope: analytics:write. Chipp MCP: apps

Discovery

Questions across every agent you can reach, and the integration catalog.

find_agents_by_capability

Find which of your agents can do something: what each agent is connected to or has switched on (hosted integrations, custom actions, MCP servers, knowledge sources, channels, built-ins). An org API key searches only its own org.

Scope: apps:read. Chipp MCP: apps

Returns: agents rows with the agent id, name, org, workspace, published and the matching capabilities.

search_integration_catalog

Search the hosted and MCP integration catalogs by provider name, key or alias. Check this before building a custom integration.

Scope: apps:read. Chipp MCP: integrations

Returns: matches with each entry’s nextStep. A result with error means the catalog could not be read, so availability is unverified.

App Administration

Access, placement, domains and workspace defaults.

add_whitelisted_email

Add an email to an app’s access whitelist. Idempotent: an email already there returns alreadyExists: true.

Scope: apps:write. Chipp MCP: app-settings

remove_whitelisted_email

Remove an email from an app’s access whitelist. Idempotent.

Scope: apps:write. Chipp MCP: app-settings

move_app

Move an app to another workspace you belong to. An org API key can only move within its org.

Scope: apps:write. Chipp MCP: apps

get_domain_status

Live SSL and DNS status for an app’s custom chat domains, with the exact DNS records to enter.

Scope: apps:read. Chipp MCP: apps

Returns: hostnames with sslStatus, sslFailureReason, userMessage, dcvToken and dnsRecords.

update_receipt_sync_visibility

Show or hide the Receipt Sync add-on in signed-in consumers’ chat menu. Hiding it does not disconnect anyone. Idempotent.

Scope: apps:write. Chipp MCP: app-settings

get_workspace_app_defaults

Read the access and compliance defaults stamped onto new apps in a workspace, and which compliance fields the plan does not support.

Scope: workspace:read. Chipp MCP: app-settings

Returns: defaults and tierLockedFields.

update_workspace_app_defaults

Replace a workspace’s App Defaults for new apps (existing apps are unchanged). Org owners and admins only.

Scope: workspace:write. Chipp MCP: app-settings

App Connections

Switch an app’s integrations on or off and schedule its knowledge sources.

set_integration_active

Turn an MCP integration on the app on or off.

Scope: actions:write. Chipp MCP: integrations

toggle_platform_managed_integration

Enable or disable a platform-managed hosted integration (Chipp holds the credentials). Verifies the result; a blocked result names the reason.

Scope: actions:write. Chipp MCP: integrations

set_factory_integration_enabled

Let the app’s signed-in end users connect their own Gmail, Google Drive, Google Calendar or Google Sheets account.

Scope: actions:write. Chipp MCP: integrations

set_mcp_write_access

Turn approval-gated write access on or off for a Vanta integration. Vanta connections are read-only by default. With write access on, the agent can propose changes in Vanta, and a member of your organization approves each change on an approval card before it runs.

Scope: actions:write. Chipp MCP: app-settings

add_sitemap_source

Add a sitemap as a knowledge source that adds newly published pages on each scheduled refresh.

Scope: knowledge:write. Chipp MCP: knowledge

update_knowledge_source

Rename a knowledge source and/or set its auto-refresh interval.

Scope: knowledge:write. Chipp MCP: knowledge

Utilities

get_me

Get the current authenticated identity: user email, all accessible organizations, tier, and scopes. Use this to verify which account the MCP is connected to.

Scope: none (any valid token). Chipp MCP: core

No parameters.

search_docs

Search Chipp’s platform documentation with a natural-language query. Returns the most relevant doc excerpts, useful for answering “how do I…” questions about Chipp itself. (Distinct from search_documentation, which searches an app’s own knowledge base.)

Scope: none (any valid token). Chipp MCP: core

get_book

Read Chipp’s book Autonomous Development. With no arguments it returns the book’s metadata and table of contents. With chapter it returns one page of that chapter’s markdown; with query it returns the best passages, each with a citation. The full text is for paying Chipp users: when your organization is on a paid plan you get chapter text and full passages; otherwise you get the table of contents and short cited snippets, and chapter reads answer BOOK_REQUIRES_PAID_PLAN.

Scope: none (any valid token). Chipp MCP: core

Appendix

Permission Scopes

A write scope also grants its read scope.

Common Error Codes

Next Steps

• Common Workflows - Step-by-step examples
• Rate Limits - Usage limits and best practices
• Authentication - Token management
• Builder API - REST API with per-app keys (sessions, consumers, conversation logging)
• Org Export API - Org-wide transcript export with chipp_org_ keys