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:

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"

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.

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'"

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

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"

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.

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

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

get_usage_by_app

Get token usage broken down by app for the organization.

Scope: billing:read

Returns: Per-app totals for call_count, total_input_tokens, and total_output_tokens.

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

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

Appendix

Permission Scopes

Common Error Codes

Next Steps

• Common Workflows - Step-by-step examples
• Rate Limits - Usage limits and best practices
• Authentication - Token management