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

Example:

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

get_app

Get detailed information about a specific application.

Scope: apps:read

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

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 existing application’s properties.

Scope: apps:write

Example:

"Rename app 123 to 'Support Bot v2'"
"Make my FAQ app publicly listed"

delete_app

Soft-delete an application.

Scope: apps:write

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

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 within your organization.

Scope: apps:read

publish_app

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

Scope: apps:write

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

list_app_versions

List published version history for an app.

Scope: apps:read

duplicate_app

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

Scope: apps:write

restore_app_version

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

Scope: apps:write

rollback_app_version

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

Scope: apps:write

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

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

Configuration

Manage application settings, system prompts, and branding.

get_system_prompt

Get the system prompt for an application.

Scope: apps:read

update_system_prompt

Update an application’s system prompt.

Scope: apps:write

get_model

Get the AI model configuration for an application.

Scope: apps:read

update_model

Change the AI model for an application.

Scope: apps:write

get_settings

Get detailed settings including RAG configuration.

Scope: apps:read

update_settings

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

Scope: apps:write

update_branding

Update visual branding for the application.

Scope: apps:write

list_suggestions

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

Scope: apps:read

update_suggestions

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

Scope: apps:write

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

set_tool_override

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

Scope: apps:write

get_default_capabilities

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

Scope: apps:read

Knowledge Sources

Manage RAG (Retrieval-Augmented Generation) knowledge bases.

list_knowledge_sources

List all knowledge sources for an application.

Scope: knowledge:read

get_knowledge_source

Get details about a specific knowledge source.

Scope: knowledge:read

add_url_source

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

Scope: knowledge:write

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

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

refresh_knowledge_source

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

Scope: knowledge:write

list_active_crawls

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

Scope: knowledge:read

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

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

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

link_knowledge_source

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

Scope: knowledge:write

unlink_knowledge_source

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

Scope: knowledge:write

list_linked_knowledge_sources

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

Scope: knowledge:read

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

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

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

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

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

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

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

search_conversations

Search conversations with filters.

Scope: analytics:read

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

get_top_queries

Get the most common user queries.

Scope: analytics:read

get_model_usage

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

Scope: analytics:read

get_response_time_analytics

Get response time statistics based on message timestamps.

Scope: analytics:read

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

search_messages

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

Scope: analytics:read

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

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

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

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

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

export_conversations

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

Scope: analytics:read

Tags

Manage intent tags for message classification and automated responses.

list_tags

List all tags for an application.

Scope: apps:read

get_tag

Get details for a specific tag including utterances.

Scope: apps:read

create_tag

Create a new intent tag.

Scope: apps:write

Action types:

• staticText: Replace AI response with fixed text
• freeze: Stop conversation flow
• notification: Send webhook or email alert

Example:

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

update_tag

Update an existing tag.

Scope: apps:write

delete_tag

Delete a tag.

Scope: apps:write

list_tag_instances

List messages that matched a specific tag.

Scope: analytics:read

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

generate_utterances

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

Scope: apps:write

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

add_tag_examples

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

Scope: apps:write

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

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

update_tag_example

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

Scope: apps:write

delete_tag_example

Delete (detach) a tag example.

Scope: apps:write

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

Evaluations

Create and run quality tests for your applications.

list_evals

List all evaluations for an application.

Scope: apps:read

get_eval

Get details for a specific evaluation.

Scope: apps:read

create_eval

Create a new evaluation with test cases for an app.

Scope: apps:write

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

delete_eval

Delete an evaluation.

Scope: apps:write

run_eval

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

Scope: apps:write

list_eval_results

List past evaluation runs.

Scope: apps:read

get_eval_result

Get detailed results from a specific evaluation run.

Scope: apps:read

Custom Actions

Manage API integrations for your applications.

list_custom_actions

List all custom actions for an application.

Scope: actions:read

get_custom_action

Get details for a specific custom action.

Scope: actions:read

create_custom_action

Create a new API integration.

Scope: actions:write

update_custom_action

Update an existing custom action.

Scope: actions:write

delete_custom_action

Delete a custom action.

Scope: actions:write

test_custom_action

Test a custom action by executing it with sample parameters.

Scope: actions:write

MCP Integrations

Connect external MCP servers to your applications.

list_mcp_integrations

List all connected MCP servers for an application.

Scope: actions:read

get_mcp_integration

Get details about a connected MCP server.

Scope: actions:read

connect_mcp_server

Connect an external MCP server to an application.

Scope: actions:write

update_mcp_integration_tools

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

Scope: actions:write

disconnect_mcp_server

Remove an MCP server connection.

Scope: actions:write

list_hosted_integrations

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

Scope: apps:read

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

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

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

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

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

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

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

unlink_component

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

Scope: components:write

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

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

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

Deployments

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

list_slack_deployments

List Slack workspace connections.

Scope: apps:read

get_slack_deployment

Get details about a Slack deployment.

Scope: apps:read

list_slack_installations

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

Scope: apps:read

connect_slack_deployment

Connect an app to a Slack workspace.

Scope: apps:write

disconnect_slack_deployment

Remove a Slack connection.

Scope: apps:write

get_whatsapp_deployment

Get WhatsApp business configuration.

Scope: apps:read

get_voice_config

Get voice agent configuration.

Scope: apps:read

update_voice_config

Update voice agent settings.

Scope: apps:write

get_email_deployment

Get email channel configuration.

Scope: apps:read

update_email_deployment

Update email channel settings.

Scope: apps:write

get_discord_deployment

Get the Discord bot integration status for an app.

Scope: apps:read

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

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

get_consumer

Get details about a specific consumer including their session count.

Scope: analytics:read

update_consumer

Update a consumer’s credit balance or subscription status.

Scope: apps:write

get_user_memories

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

Scope: analytics:read

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

get_workspace

Get details about a specific workspace.

Scope: workspace:read

list_workspace_members

List members of a workspace.

Scope: workspace:read

create_workspace

Create a new workspace in your organization.

Scope: workspace:write

Example:

"Create a new workspace called Marketing"

Billing

View subscription and credit information.

get_subscription

Get subscription details for an organization.

Scope: billing:read

get_credits

Get credit balance and usage.

Scope: billing:read

get_usage

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

Scope: billing:read

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

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

Prompt Engineering

AI-assisted tools for improving prompts and selecting models.

list_available_models

List all AI models available for use.

Scope: apps:read

generate_system_prompt

Generate a new system prompt from a description.

Scope: apps:write

improve_system_prompt

Use AI to analyze and improve an existing system prompt.

Scope: apps:write

recommend_model

Get AI-powered model recommendations for your use case.

Scope: apps:read

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

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

get_action_collection

Get details for a specific action collection.

Scope: actions:read

create_action_collection

Create a new action collection.

Scope: actions:write

update_action_collection

Update an action collection’s name or description.

Scope: actions:write

delete_action_collection

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

Scope: actions:write

link_collection_to_app

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

Scope: actions:write

unlink_collection_from_app

Remove an action collection from an application.

Scope: actions:write

list_linked_collections

List all action collections linked to a specific application.

Scope: actions:read

update_collection_sharing

Update the sharing scope of an action collection.

Scope: actions:write

• 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

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

get_app_variable

Get details for a specific application variable.

Scope: apps:read

create_app_variable

Create a new application variable.

Scope: apps:write

update_app_variable

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

Scope: apps:write

delete_app_variable

Delete an application variable.

Scope: apps:write

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

Returns: enabled, every, prompt, checklist, targets, and model.

update_heartbeat_config

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

Scope: apps:write

list_heartbeat_runs

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

Scope: analytics:read

trigger_heartbeat

Manually trigger a heartbeat run for an app.

Scope: apps:write

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

list_available_agents

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

Scope: apps:read

link_agent

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

Scope: apps:write

Example:

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

unlink_agent

Remove an agent link from an app.

Scope: apps:write

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

get_database_connection

Get details about a database connection.

Scope: apps:read

create_database_connection

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

Scope: apps:write

delete_database_connection

Delete a database connection from an app.

Scope: apps:write

test_database_connection

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

Scope: apps:write

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

create_consumer_package

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

Scope: apps:write

update_consumer_package

Update a consumer credit package.

Scope: apps:write

delete_consumer_package

Delete a consumer credit package (soft delete).

Scope: apps:write

get_monetization_stats

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

Scope: analytics:read

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

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. Takes no parameters and requires no specific scope.

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.)

Appendix

Permission Scopes

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