Agent skill

mcp-chatkit-integration

Build MCP (Model Context Protocol) servers and integrate them with OpenAI ChatKit and Agents SDK. Use this skill when Claude needs to: (1) Create an MCP server using FastMCP with Streamable HTTP transport (2) Define MCP tools for agents to call (3) Integrate MCP servers with OpenAI Agents SDK using MCPServerStreamableHttp (4) Build ChatKit server backends that use MCP tools (5) Handle multi-tenant user context injection for MCP tools (6) Debug MCP connection timeouts or tool execution issues (7) Deploy MCP servers in Docker/Kubernetes environments

View SKILL.md on GitHub Repository
Stars 9
Forks 5

Install this agent skill to your Project

npx add-skill https://github.com/Rehan-Ul-Haq/my-skills/tree/main/skills/mcp-chatkit-integration

SKILL.md

MCP + ChatKit Integration

Build MCP servers and integrate them with OpenAI ChatKit for conversational AI applications.

Architecture Overview

┌─────────────┐     ┌─────────────────┐     ┌─────────────┐
│   ChatKit   │────▶│  Dispatcher     │────▶│ MCP Server  │
│   Frontend  │     │  Agent (SDK)    │     │  (FastMCP)  │
└─────────────┘     └─────────────────┘     └─────────────┘
                           │                       │
                           ▼                       ▼
                    MCPServerStreamableHttp    Database/APIs

Quick Start

1. MCP Server (FastMCP)

python
from fastmcp import FastMCP
from fastapi import FastAPI

mcp = FastMCP("My Tools")

@mcp.tool()
async def my_tool(user_id: str, param: str) -> dict:
    """Tool description for the agent."""
    return {"result": f"Processed {param} for {user_id}"}

# Mount as FastAPI app
mcp_asgi = mcp.http_app(transport="streamable-http", path="/")
app = FastAPI(lifespan=mcp_asgi.lifespan)
app.mount("/mcp", mcp_asgi)

2. Agent with MCP (OpenAI Agents SDK)

python
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

mcp_server = MCPServerStreamableHttp(
    name="My MCP",
    params={"url": "http://localhost:8001/mcp", "timeout": 60},
    client_session_timeout_seconds=30,
    cache_tools_list=True,
)

async with mcp_server:
    agent = Agent(
        name="Assistant",
        instructions=dynamic_instructions,  # Function for user_id injection
        model="gpt-4o",
        mcp_servers=[mcp_server],
    )
    result = await Runner.run(agent, "Hello", context=my_context)

3. ChatKit Server

python
from chatkit.server import ChatKitServer
from chatkit.agents import stream_agent_response

class MyChatKitServer(ChatKitServer[dict]):
    async def respond(self, thread, input, context):
        result = Runner.run_streamed(agent, input, context=agent_ctx)
        async for event in stream_agent_response(agent_ctx, result):
            yield event

Key Patterns

User ID Injection (Multi-Tenant)

MCP tools need user_id for data isolation. Use dynamic instructions:

python
def get_dynamic_instructions(context_wrapper, agent) -> str:
    user_id = "anonymous"
    ctx = context_wrapper.context

    if hasattr(ctx, "user_id"):
        user_id = ctx.user_id
    elif hasattr(ctx, "request_context"):
        user_id = ctx.request_context.get("user_id", "anonymous")

    return BASE_PROMPT.format(user_id=user_id)

Timeout Configuration

Default MCP timeout is 5 seconds - increase for database operations:

python
MCPServerStreamableHttp(
    params={"url": url, "timeout": 60},
    client_session_timeout_seconds=30,  # MCP session read timeout
)

Error Handling in ChatKit

python
from chatkit.types import ThreadItemAddedEvent, AssistantMessageItem

except Exception as e:
    error_item = AssistantMessageItem(
        id=store.generate_item_id("message", thread, context),
        content=[AssistantMessageContent(type="output_text", text="Error occurred")],
    )
    yield ThreadItemAddedEvent(type="item.added", item=error_item)

Reference Files

  • references/mcp-server.md: Complete MCP server patterns with FastMCP
  • references/agent-integration.md: OpenAI Agents SDK + MCP integration
  • references/chatkit-server.md: ChatKit server implementation patterns
  • references/deployment.md: Docker/Kubernetes deployment configuration

Common Issues

Issue Solution
Timeout after 5s Increase client_session_timeout_seconds
Tools not discovered Check MCP URL (no trailing slash)
user_id not passed Use dynamic instructions pattern
Closure bug in tool wrappers Use SDK's built-in mcp_servers parameter
ThreadItemCreatedEvent not found Use ThreadItemAddedEvent instead

Environment Variables

bash
MCP_SERVER_URL=http://localhost:8001/mcp  # No trailing slash
OPENAI_API_KEY=your_key

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

Rehan-Ul-Haq/my-skills

mcp-builder

Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).

9 5
Explore
Rehan-Ul-Haq/my-skills

containerize-apps

Containerizes applications with impact-aware Dockerfiles and docker-compose configurations. This skill should be used when containerizing projects for Docker, creating Dockerfiles, docker-compose files, or preparing applications for Kubernetes deployment. It performs impact analysis first (env vars, network topology, auth/CORS), then generates properly configured container configs. Invokes the impact-analyzer subagent for comprehensive project scanning.

9 5
Explore
Rehan-Ul-Haq/my-skills

writing-dockerfile

Generates secure, production-ready Dockerfiles with multi-stage builds and security hardening. Use when Claude needs to write Dockerfiles for containerized applications.

9 5
Explore
Rehan-Ul-Haq/my-skills

skill-validator

Validates skills against production-level criteria with 9-category scoring. This skill should be used when reviewing, auditing, or improving skills to ensure quality standards. Evaluates structure, content, user interaction, documentation, domain standards, technical robustness, maintainability, zero-shot implementation, and reusability. Returns actionable validation report with scores and improvement recommendations.

9 5
Explore
Rehan-Ul-Haq/my-skills

discovering-intent

Conducts discovery conversations to understand user intent and agree on approach before taking action. Use when users ask for recommendations, need brainstorming, want to clarify requirements, or when requests could be misunderstood. Prevents building the wrong thing by uncovering WHY behind WHAT.

9 5
Explore
Rehan-Ul-Haq/my-skills

creating-chatgpt-widgets

Create production-grade widgets for ChatGPT Apps using the OpenAI Apps SDK. Use when users ask to build widgets, UI components, or visual interfaces for ChatGPT applications. Supports any widget type including progress trackers, quiz interfaces, content viewers, data cards, carousels, forms, charts, dashboards, maps, video players, or custom interactive elements. IMPORTANT - Always clarify requirements before building. Creates complete implementations following official OpenAI UX/UI guidelines with window.openai integration, theme support, and accessibility.

9 5
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results