MCP Server Integration

Listing MCP Server Integrations

Retrieving a list of your MCP Server integrations allows you to inventory all configured external connections, review their settings, and manage their associations with other platform resources like skillsets and blueprints. The list endpoint supports pagination and filtering to help you efficiently navigate large numbers of integrations.

To retrieve your MCP Server integrations, send a GET request to the list endpoint:

Pagination

The list endpoint supports cursor-based pagination for efficient navigation through large result sets. Use the cursor parameter to fetch subsequent pages:

• cursor: Pagination token returned from previous request
• take: Number of items to retrieve per page (default varies by implementation)
• order: Sort order, either asc or desc (default: desc)

Filtering by Blueprint

You can filter integrations associated with specific blueprints:

This is particularly useful when managing integrations within the context of a specific project or workflow.

Filtering by Metadata

Filter integrations based on custom metadata fields using deep object notation:

Metadata filtering enables flexible organization and retrieval of integrations based on your own tagging and categorization schemes.

Response Format

The endpoint returns a list of integration objects:

Streaming Response (JSONL)

For real-time processing of large result sets, the endpoint supports JSONL (JSON Lines) streaming format. Set the Accept header to request streaming:

Each line in the response stream is a JSON object:

Important Notes:

• Only integrations owned by the authenticated user are returned
• The skillsetId field indicates which skillset the integration is linked to, determining what abilities are available through the MCP server
• Blueprint associations allow grouping integrations with related resources for complex workflows
• Metadata is flexible and can store arbitrary key-value pairs for custom organization and filtering

The Model Context Protocol (MCP) Server Integration allows you to expose your ChatBotKit skillsets as standardized MCP servers that external consumers can connect to and use. This integration transforms your skillsets—which contain abilities, tools, and functions—into MCP-compliant endpoints that can be consumed by any MCP-compatible client, including other AI systems, development tools, and custom applications.

By creating an MCP server integration, you're essentially publishing your skillset's capabilities through a standardized protocol, making them accessible to external consumers who want to leverage your tools, functions, and AI capabilities in their own applications. This enables powerful integration scenarios where your ChatBotKit resources become building blocks that others can incorporate into their AI workflows.

Creating MCP Server Integrations

To create an MCP server integration, you need to specify which skillset you want to expose as an MCP server. The skillset contains the abilities and functions that will be made available to external consumers through the MCP protocol.

Create an MCP server integration by sending a POST request:

The API will return the integration ID and automatically generate a secure access token for authentication:

Exposing Skillsets via MCP

When you create an MCP server integration, you specify a skillsetId that points to the skillset you want to expose. The skillset defines what capabilities will be available to external consumers through the MCP protocol.

All abilities, tools, and functions defined in the skillset become discoverable and callable by external MCP clients. This allows you to package your AI capabilities and make them available as reusable components that other applications can integrate with.

External consumers can then connect to your MCP server using standard MCP clients and invoke the abilities and functions you've exposed through your skillset, enabling them to leverage your AI capabilities in their own applications.

Access Token Security

During integration creation, a secure access token is automatically generated. This token authenticates requests from external consumers who want to access your MCP server, ensuring that only authorized clients can utilize the capabilities you're exposing.

Important Security Considerations:

• Store the access token securely and share it only with trusted consumers
• Never expose access tokens in client-side code or public repositories
• Treat access tokens with the same care as API keys
• Provide the access token to external consumers through secure channels
• External consumers must include this token in their MCP client configuration
• Consider rotating access tokens periodically for enhanced security
• Monitor token usage to detect unauthorized access attempts

How External Consumers Use Your MCP Server

Once you've created an MCP server integration, external consumers can connect to it using any MCP-compatible client. They will need:

The MCP Server Endpoint: A URL provided by ChatBotKit that points to your exposed skillset capabilities.

The Access Token: The authentication token generated during integration creation, which you provide to authorized consumers.

MCP Client Software: Any application or tool that implements the MCP client protocol, such as AI development environments, automation tools, or custom applications.

External consumers configure their MCP client with these credentials, and the client can then discover and invoke the abilities and functions from your skillset, integrating your AI capabilities into their workflows.

MCP Protocol Overview

The Model Context Protocol defines a standard interface for exposing and consuming AI capabilities. When you expose a skillset as an MCP server, it provides:

Tools and Functions: Your skillset's abilities become callable operations that external consumers can invoke to perform specific tasks, such as querying knowledge bases, processing data, or executing custom logic.

Context Providers: If your skillset includes data sources or knowledge bases, these become accessible to external consumers as context providers.

Resource Handlers: Your skillset's resource access capabilities become available to external clients through standardized MCP resource interfaces.

Discoverable Capabilities: External MCP clients can automatically discover what functions and tools your skillset exposes, making integration seamless.

By exposing your skillset through MCP, you make your AI capabilities available in a standardized format that any MCP-compatible system can understand and utilize.

Integration with Blueprints

MCP server integrations can be associated with blueprints for organized resource management. When you include a blueprintId during creation, the integration becomes part of that blueprint's resource collection, making it easier to manage related integrations, skillsets, and exposure configurations together.

This is particularly useful when you're exposing multiple skillsets as MCP servers for different purposes or consumer groups, as you can organize them under blueprints for simplified management and access control.

Use Cases

MCP server integrations are ideal for:

Sharing AI Capabilities: Make your custom AI tools and functions available to partners, customers, or other applications.

Building AI Marketplaces: Expose specialized skillsets that others can subscribe to and use in their own AI systems.

Enterprise Integration: Allow different departments or systems within your organization to consume shared AI capabilities through a standardized protocol.

Partner Integrations: Provide external partners with access to your AI tools and knowledge bases through secure MCP endpoints.

Development Tool Integration: Make your skillsets available to AI development environments and IDEs that support the MCP protocol.

Multi-System Orchestration: Enable external workflow automation systems to incorporate your AI capabilities into their processes.

Best Practices

Design Clear Skillsets: Structure your skillsets with clear, well-documented abilities that external consumers can easily understand and use.

Provide Documentation: Create comprehensive documentation for consumers explaining what capabilities your MCP server exposes and how to use them.

Monitor Usage: Track how external consumers are using your MCP server to understand usage patterns and identify optimization opportunities.

Implement Rate Limiting: Consider implementing usage quotas or rate limits to prevent abuse of your exposed capabilities.

Version Your Skillsets: When updating skillsets exposed via MCP, consider versioning to avoid breaking existing consumer integrations.

Secure Access Tokens: Distribute access tokens securely and maintain records of which consumers have access to which MCP servers.

Test Integration: Before sharing your MCP server with external consumers, test it thoroughly using MCP client tools to ensure capabilities work as expected.

Important Notes:

• The skillset you expose must contain abilities and functions for external consumers to utilize
• Access tokens are generated automatically and cannot be retrieved later; capture and store them securely during integration setup
• External consumers need both the MCP server endpoint URL and access token to connect
• You control what capabilities are exposed by carefully designing the skillset before creating the MCP server integration
• Changes to the linked skillset will be reflected in the MCP server capabilities
• Consider the security implications of exposing your skillset to external consumers and implement appropriate access controls

Deleting MCP Server Integrations

Permanently remove an MCP Server integration when you no longer need to expose your ChatBotKit skillsets via the Model Context Protocol. Deleting an integration immediately stops external MCP clients from accessing the skillsets that were shared through this server endpoint.

Delete an MCP Server integration by sending a POST request:

The API confirms deletion by returning the integration ID:

Immediate Effects of Deletion

Access Termination: External MCP clients can no longer access the skillsets exposed through this integration. Any applications or services using this MCP server endpoint will immediately lose access.

Token Invalidation: Access tokens associated with this integration are invalidated immediately. Clients attempting to use these tokens will receive authentication errors.

Resource Preservation: The skillsets, abilities, and other ChatBotKit resources that were exposed through this integration remain unchanged in your account. Only the MCP server endpoint configuration is removed.

Blueprint Association: If this integration was part of a blueprint, removing it doesn't affect other resources in the blueprint. The blueprint continues to function with its remaining resources.

Before You Delete

Consider these important factors before deleting an MCP Server integration:

Active Clients: Identify any external applications or services currently using this MCP server endpoint. Deletion will immediately break their access to your skillsets.

Alternative Access: Ensure clients have alternative ways to access the functionality they need, or plan for service migration before deletion.

Documentation Updates: Update any documentation or configuration guides that reference this MCP server endpoint URL or access token.

Coordination: If multiple teams or organizations use this integration, coordinate the deletion to avoid unexpected service disruptions.

Common Deletion Scenarios

Service Decommissioning: When retiring a service or feature that relied on MCP protocol access to ChatBotKit skillsets.

Security Rotation: Removing old integrations as part of security credential rotation or access control policy changes.

Migration: Deleting test or staging integrations after migrating to production configurations.

Cleanup: Removing unused or experimental integrations to maintain an organized account.

Alternative to Deletion

If you need to temporarily disable access without permanently deleting the integration, consider these alternatives:

Token Rotation: Generate new access tokens and distribute them only to authorized clients, effectively revoking access for clients with old tokens.

Skillset Modification: Remove skillsets from the integration or modify their availability to control what external clients can access.

These approaches preserve your integration configuration while controlling access, making it easier to restore service if needed without recreating the entire integration.

Fetching MCP Server Integration Details

Retrieve comprehensive configuration details for an MCP Server integration, including exposed skillsets, access tokens, and server endpoint information. This operation provides all the information needed to understand how your ChatBotKit abilities are being shared via the Model Context Protocol.

Fetch an MCP Server integration by sending a POST request:

The API returns complete integration details:

Understanding the Response

Integration Identity: The response includes the integration ID, name, and description you provided during creation, helping you identify and document the purpose of this MCP server endpoint.

Skillset Configuration: The skillsetIds array shows which ChatBotKit skillsets are exposed through this MCP server. External MCP clients can invoke abilities from these skillsets using the Model Context Protocol.

Access Token: The accessToken field contains the authentication credential that external MCP clients must use to access this server. Keep this token secure and distribute it only to authorized clients.

Blueprint Association: If the integration is part of a blueprint, the blueprintId shows which blueprint it belongs to, helping you understand how this integration fits into your broader resource organization.

Metadata and Timestamps: Custom metadata fields and creation/update timestamps provide additional context about the integration's configuration and history.

Common Use Cases for Fetching

Configuration Verification: Before making updates, fetch the current configuration to understand what will change and plan modifications carefully.

Access Token Retrieval: When setting up new external clients, fetch the integration to retrieve the access token they'll need for authentication.

Audit and Documentation: Retrieve integration details for documentation, compliance requirements, or internal audit processes showing what abilities are exposed externally.

Troubleshooting: When debugging MCP client issues, fetch integration details to verify that skillsets and access tokens are configured correctly.

Automated Management: Programmatically retrieve integration configurations for monitoring, backup, or synchronization with external management systems.

Security Considerations

The fetch operation returns the access token used by external clients to authenticate with your MCP server. This token provides access to all skillsets exposed through the integration:

Token Protection: Store the retrieved access token securely and never commit it to version control systems or share it publicly.

Access Control: Only fetch integration details from systems and accounts that have legitimate need to access the configuration information.

Token Rotation: If the access token is compromised, create a new integration with fresh credentials and delete the compromised one to ensure security.

Updating MCP Server Integrations

Modify an existing MCP Server integration to change which skillsets are exposed, update organizational information, or associate the integration with different blueprints. Updates take effect immediately and apply to all subsequent MCP client requests using this server endpoint.

Update an MCP Server integration by sending a POST request with new configuration:

The API confirms the update:

Updatable Parameters

name and description: Update the integration's identification and documentation. These changes help you maintain clear records of what each MCP server endpoint provides and are immediately visible in the ChatBotKit interface and API responses.

skillsetIds: Modify which ChatBotKit skillsets are exposed through this MCP server. You can add new skillsets to expand available functionality, remove skillsets to restrict access, or replace the entire skillset collection to change what external clients can invoke.

blueprintId: Associate the integration with a different blueprint, or remove the blueprint association by setting it to null. This affects how the integration is organized within your account's resource management structure.

meta: Add or modify custom metadata fields for categorization, filtering, and management purposes according to your organizational needs.

Skillset Management

When updating skillsetIds, you're controlling which abilities external MCP clients can access through this server endpoint:

Adding Skillsets: Include additional skillset IDs in the array to expose more abilities to external clients. New skillsets become available immediately for clients to discover and invoke.

Removing Skillsets: Exclude skillset IDs from the array to stop exposing certain abilities. External clients will no longer be able to invoke abilities from removed skillsets, even if they previously had access.

Replacing Skillsets: Provide a completely different set of skillset IDs to fundamentally change what this MCP server provides to external clients.

The update replaces the entire skillset list, so make sure to include all skillsets you want to remain exposed, not just newly added ones.

Update Behavior and Timing

Immediate Effect: Configuration changes apply immediately to all subsequent MCP client requests. Clients that query the server after the update will see the new skillset configuration.

Active Connections: MCP clients with active connections continue using cached server information until they refresh. Encourage clients to refresh their tool/ability cache after major updates.

Access Token Unchanged: Updates don't affect the integration's access token. External clients continue using the same authentication credentials without needing reconfiguration.

Backward Compatibility: If you remove skillsets that external clients were using, those clients will receive errors when trying to invoke abilities from removed skillsets. Coordinate skillset removals with client teams to avoid service disruptions.

Common Update Scenarios

Capability Expansion: Add new skillsets to expose additional abilities as you develop and deploy new AI agent functionality.

Access Control: Remove skillsets to restrict what external clients can access, implementing tighter security or limiting functionality.

Feature Updates: Update skillsets when you've improved or modified the abilities they contain, ensuring clients access the latest functionality.

Organizational Restructuring: Change blueprint association when reorganizing how resources are grouped and managed in your account.

Documentation Maintenance: Update name and description to reflect current usage, especially as the integration's purpose evolves over time.

Best Practices

Communicate Changes: When updating skillsets, notify teams using this MCP server endpoint about what's changing and when, especially for removals.

Version Metadata: Use metadata fields to track which version of skillsets are currently exposed, aiding in troubleshooting and change management.

Test Before Production: If making significant skillset changes, consider creating a test integration first to verify the new configuration works as expected before updating production endpoints.

Monitor After Updates: Watch for errors or unexpected behavior from external clients after updating skillset configuration, especially when removing abilities.

Document Changes: Maintain records of what changed, when, and why for audit trails and troubleshooting purposes.