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:

GET /api/v1/integration/mcpserver/list

http

Pagination

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

GET /api/v1/integration/mcpserver/list?cursor=eyJpZCI6Im1jcF8xMjMifQ&take=20

http
  • 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:

GET /api/v1/integration/mcpserver/list?blueprintId=bp_abc123

http

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:

GET /api/v1/integration/mcpserver/list?meta[environment]=production&meta[region]=us-east

http

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:

{
  "items": [
    {
      "id": "mcp_abc123",
      "name": "Custom Analytics Service",
      "description": "Integration with internal analytics platform",
      "blueprintId": "bp_xyz789",
      "skillsetId": "skill_def456",
      "meta": {
        "environment": "production",
        "version": "2.0"
      },
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-16T14:20:00.000Z"
    }
  ]
}

json

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:

GET /api/v1/integration/mcpserver/list
Accept: application/jsonl

http

Each line in the response stream is a JSON object:

{"type":"item","data":{"id":"mcp_abc123","name":"Service 1",...}}
{"type":"item","data":{"id":"mcp_def456","name":"Service 2",...}}

jsonl

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

Authentication

Every request to an MCP Server Integration endpoint requires a static access token. This token acts as a kill-switch: rotating it in the dashboard immediately revokes access for all clients, regardless of any other credentials they hold. It is always required.

Standard Authentication

Pass the access token in the Authorization header using the Bearer scheme:

POST /api/v1/integration/mcpserver/{mcpserverIntegrationId}/mcp
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

http

You can also pass it as an authorization query parameter, which is useful for tools that do not support custom headers:

POST /api/v1/integration/mcpserver/{mcpserverIntegrationId}/mcp?authorization=YOUR_ACCESS_TOKEN
Content-Type: application/json

http

OAuth / IdP Authentication

When an OAuth connection is configured on the integration, end-users authenticate through your Identity Provider (IdP) using the standard OAuth 2.0 Authorization Code flow with PKCE. The MCP client (e.g. Claude) receives a short-lived JWT Bearer token issued by ChatBotKit after the IdP login completes, and sends it in the Authorization header.

Because the Authorization header is occupied by the JWT in this flow, the static access token must be supplied via the authorization query parameter at the same time:

POST /api/v1/integration/mcpserver/{mcpserverIntegrationId}/mcp?authorization=YOUR_ACCESS_TOKEN
Authorization: Bearer OAUTH_JWT_TOKEN
Content-Type: application/json

http

Both credentials are validated on every request. If either is missing or invalid the server responds with 401 Unauthorized.

Revoking Access

To immediately cut off all access to an integration - for example after a security incident - rotate the static access token from the dashboard. The new token takes effect instantly. Existing OAuth sessions become invalid on the next request because the static token check always runs, even for users with valid JWT tokens.

Session Management

MCP Server Integrations use session management to maintain context and state across multiple requests from client applications. Sessions enable your skillsets to provide consistent, contextual responses throughout extended interactions, similar to how conversations maintain continuity in chat applications.

Understanding Sessions

A session represents a persistent context for interactions between a client application and your MCP server integration. Each session is uniquely identified and bound to your user account, ensuring that different clients or applications maintain separate, isolated contexts.

Sessions are managed automatically through HTTP headers, requiring minimal implementation effort from client applications. The platform handles session creation, validation, and lifecycle management transparently, allowing you to focus on building your integration logic.

Session Lifecycle

When a client application connects to your MCP server endpoint, the session lifecycle proceeds as follows:

  1. Initial Connection: The first request from a client automatically creates a new session. The server returns a unique session identifier in the mcp-session-id response header.

  2. Session Reuse: Subsequent requests from the same client should include the mcp-session-id header to continue using the same session. This maintains context across multiple tool invocations.

  3. Session Validation: Each request validates that the session belongs to the authenticated user. Sessions from other users or invalid session identifiers result in automatic creation of new sessions.

  4. Session Expiration: Sessions automatically expire after 24 hours of inactivity. Active sessions are kept alive automatically - each request extends the session lifetime by another 24 hours.

Implementing Session Support

To implement session support in your client application, capture the mcp-session-id header from the initial response and include it in subsequent requests:

Initial Request:

POST /api/v1/integration/mcpserver/{mcpserverIntegrationId}/mcp
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 1
}

http

Server Response:

HTTP/1.1 200 OK
mcp-session-id: clx8k9j2m0000abcdefghijk
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "result": { ... },
  "id": 1
}

http

Subsequent Requests:

POST /api/v1/integration/mcpserver/{mcpserverIntegrationId}/mcp
Authorization: Bearer YOUR_ACCESS_TOKEN
mcp-session-id: clx8k9j2m0000abcdefghijk
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": { ... },
  "id": 2
}

http

Session Security and Isolation

Sessions are strictly bound to the authenticated user account. The platform enforces the following security guarantees:

  • User Isolation: Sessions cannot be shared between different user accounts. Each session is validated against the authentication token on every request.

  • Integration Isolation: Each MCP server integration maintains separate session namespaces, preventing cross-contamination between different integrations.

  • Automatic Security: Invalid or tampered session identifiers are rejected automatically, with new sessions created as needed to ensure service continuity.

  • Secure Storage: Session data is encrypted and stored securely, protecting sensitive context information.

Best Practices

When implementing session management in your client applications:

  • Always preserve session IDs: Store the mcp-session-id header value and include it in all subsequent requests to maintain context.

  • Handle session expiration gracefully: If a session expires, the server will automatically create a new session. Your client should detect this (by comparing session IDs) and reset any local context as needed.

  • Don't share sessions: Each client instance should maintain its own session. Sharing session IDs between different clients or users will result in authentication failures.

  • Monitor session activity: For long-running applications, be aware of the 24-hour inactivity timeout. Regular requests keep sessions alive automatically.

Note: Session management is optional but recommended. Clients that don't implement session support will receive a new session for each request, which may limit the ability of your skillsets to maintain context across multiple interactions.

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:

POST /api/v1/integration/mcpserver/create
Content-Type: application/json

{
  "name": "Customer Support Tools",
  "description": "Exposes customer support abilities and knowledge base access",
  "skillsetId": "skillset_abc123"
}

http

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

{
  "id": "mcpserver_xyz789"
}

json

Configuring OAuth Authentication

To restrict MCP server access to authenticated users through your Identity Provider (IdP), include an oAuthConnectionId when creating the integration. This links the MCP server to an OAuth connection configured in your account, enabling end-users to authenticate via your IdP before accessing the server.

POST /api/v1/integration/mcpserver/create
Content-Type: application/json

{
  "name": "Secure AI Tools",
  "description": "MCP server with IdP-based access control",
  "skillsetId": "skillset_abc123",
  "oAuthConnectionId": "oauthconnection_xyz789"
}

http

When an OAuth connection is configured, MCP clients such as Claude perform the standard OAuth 2.0 Authorization Code flow with PKCE to obtain a short-lived JWT token. This token is then passed in the Authorization header alongside the static access token (supplied via the authorization query parameter) on every request.

The OAuth connection you reference must already exist in your account and must be a compatible OAuth 2.0 provider. Create OAuth connections through the /api/v1/oauth/connection/create endpoint before configuring IdP authentication on an MCP server integration.

When to Use OAuth Authentication:

  • Multi-user access: Allow multiple end-users to authenticate with their own IdP credentials rather than sharing a single static token
  • Enterprise SSO: Gate MCP server access behind your corporate IdP
  • Contact personalization: Automatically associate each request with the authenticated contact for personalized ability execution
  • Audit and compliance: Attribute every tool invocation to a specific authenticated user identity

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:

POST /api/v1/integration/mcpserver/{mcpserverIntegrationId}/delete
Content-Type: application/json

{}

http

The API confirms deletion by returning the integration ID:

{
  "id": "mcpserver_abc123"
}

json

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 GET request:

GET /api/v1/integration/mcpserver/{mcpserverIntegrationId}/fetch

http

The API returns complete integration details:

{
  "id": "mcpserver_abc123",
  "name": "AI Assistant Tools Server",
  "description": "MCP server exposing AI assistant abilities",
  "blueprintId": "blueprint_xyz789",
  "skillsetId": "skillset_001",
  "meta": {
    "environment": "production",
    "version": "1.0"
  },
  "createdAt": "2025-01-10T08:00:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

json

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 skillsetId field shows which ChatBotKit skillset is exposed through this MCP server. External MCP clients can invoke abilities from this skillset using the Model Context Protocol.

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:

POST /api/v1/integration/mcpserver/{mcpserverIntegrationId}/update
Content-Type: application/json

{
  "name": "Updated AI Tools Server",
  "description": "Updated MCP server with revised skillset",
  "skillsetId": "skillset_001",
  "blueprintId": "blueprint_new456"
}

http

The API confirms the update:

{
  "id": "mcpserver_abc123"
}

json

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.

skillsetId: Change which ChatBotKit skillset is exposed through this MCP server. The new skillset takes effect immediately, replacing all previously exposed abilities with those from the new skillset.

oAuthConnectionId: Configure or change the OAuth connection used for IdP-based user authentication. Set to a valid OAuth connection ID to enable user-specific authentication, or omit to leave authentication unchanged. This links the MCP server to an existing OAuth connection in your account, enabling end-users to authenticate through your Identity Provider before accessing the server.

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 skillsetId, you're replacing which abilities external MCP clients can access through this server endpoint. The new skillset takes effect immediately for all subsequent requests. Clients that previously relied on abilities from the old skillset will need to rediscover available tools after the change.

OAuth Configuration Updates

You can enable, change, or remove OAuth/IdP authentication at any time by updating the oAuthConnectionId field. When you add or change the OAuth connection, MCP clients that have already established connections will need to re-authenticate on their next request:

POST /api/v1/integration/mcpserver/{mcpserverIntegrationId}/update
Content-Type: application/json

{
  "oAuthConnectionId": "oauthconnection_new789"
}

http

After updating the OAuth connection, existing JWT tokens issued under the previous configuration become invalid. All clients must complete the OAuth flow again to obtain new tokens. The static access token is unaffected by this change.

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 static access token. External clients continue using the same static credentials without needing reconfiguration, unless the OAuth connection is also changed.

Backward Compatibility: If you change the skillset to one that removes abilities external clients were using, those clients will receive errors when trying to invoke the removed abilities. Coordinate skillset changes with client teams to avoid service disruptions.

Common Update Scenarios

Capability Expansion: Switch to a different skillset containing more abilities to expand available functionality for external clients.

Access Control: Change to a more restricted skillset or add OAuth authentication to tighten access to your MCP server.

Feature Updates: Update the skillset when you've improved or modified the abilities it contains, ensuring clients access the latest functionality.

OAuth Setup: Add an oAuthConnectionId to enable IdP-based user authentication on an existing integration that previously used only static token authentication.

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 changing skillsets, notify teams using this MCP server endpoint about what's changing and when.

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 or OAuth configuration.

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

Go to cbk.ai