AI Agent Skill HUB

MCP Server Architecture

This skill should be used when the user asks to "create an MCP server", "set up MCP server", "build ChatGPT app backend", "MCP transport type", "configure MCP endpoint", "server setup for Apps SDK", or needs guidance on MCP server architecture, transport protocols, or SDK setup for the OpenAI Apps SDK.

16 stars
bydiegosouzapw
View on GitHubInstallation ↓

Best use case

MCP Server Architecture is best used when you need a repeatable AI agent workflow instead of a one-off prompt.

This skill should be used when the user asks to "create an MCP server", "set up MCP server", "build ChatGPT app backend", "MCP transport type", "configure MCP endpoint", "server setup for Apps SDK", or needs guidance on MCP server architecture, transport protocols, or SDK setup for the OpenAI Apps SDK.

Teams using MCP Server Architecture should expect a more consistent output, faster repeated execution, less prompt rewriting.

When to use this skill

  • You want a reusable workflow that can be run more than once with consistent structure.

When not to use this skill

  • You only need a quick one-off answer and do not need a reusable workflow.
  • You cannot install or maintain the underlying files, dependencies, or repository context.

Installation

Claude Code / Cursor / Codex

$curl -o ~/.claude/skills/mcp-server-architecture/SKILL.md --create-dirs "https://raw.githubusercontent.com/diegosouzapw/awesome-omni-skill/main/skills/backend/mcp-server-architecture/SKILL.md"

Manual Installation

  1. Download SKILL.md from GitHub
  2. Place it in .claude/skills/mcp-server-architecture/SKILL.md inside your project
  3. Restart your AI agent — it will auto-discover the skill

How MCP Server Architecture Compares

Feature / AgentMCP Server ArchitectureStandard Approach
Platform SupportNot specifiedLimited / Varies
Context Awareness High Baseline
Installation ComplexityUnknownN/A

Frequently Asked Questions

What does this skill do?

This skill should be used when the user asks to "create an MCP server", "set up MCP server", "build ChatGPT app backend", "MCP transport type", "configure MCP endpoint", "server setup for Apps SDK", or needs guidance on MCP server architecture, transport protocols, or SDK setup for the OpenAI Apps SDK.

Where can I find the source code?

You can find the source code on GitHub using the link provided at the top of the page.

SKILL.md Source

# MCP Server Architecture for OpenAI Apps SDK

## Overview

MCP (Model Context Protocol) servers form the backend for ChatGPT apps built with the OpenAI Apps SDK. The server exposes tools that ChatGPT can invoke, handles authentication, and returns structured data that powers both model responses and widget UIs.

## Core Architecture

An MCP server for the Apps SDK implements three essential capabilities:

1. **List tools** - Advertise available tools with JSON Schema contracts
2. **Call tools** - Execute tool logic and return structured responses
3. **Return widgets** - Provide UI templates via resource URIs and `_meta` fields

### Data Flow

```
User prompt → ChatGPT calls MCP tool → Server executes logic →
Returns structuredContent + _meta → ChatGPT renders widget + narrates
```

## Transport Types

The Apps SDK supports two transport protocols:

### Streamable HTTP (Recommended)

Primary transport for production deployments. Use for publicly accessible servers.

**Python (FastMCP):**
```python
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-server")

@mcp.tool()
def my_tool(param: str) -> str:
    return f"Result: {param}"

if __name__ == "__main__":
    mcp.run(transport="streamable-http", host="0.0.0.0", port=8000)
```

**TypeScript:**
```typescript
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";

const server = new Server({ name: "my-server", version: "1.0.0" }, { capabilities: { tools: {} } });
const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => crypto.randomUUID() });

await server.connect(transport);
```

### Server-Sent Events (SSE)

Alternative transport for event-streaming requirements.

**Python:**
```python
mcp.run(transport="sse", host="0.0.0.0", port=8000)
```

**TypeScript:**
```typescript
import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
const transport = new SSEServerTransport("/mcp", response);
```

## SDK Setup

### Python Setup

Install the MCP Python SDK:

```bash
pip install mcp
# Or with FastAPI support
pip install "mcp[fastapi]"
```

**Minimal server structure:**
```python
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("server-name")

@mcp.tool()
def example_tool(query: str) -> dict:
    """Tool description for the model."""
    return {"result": query}

@mcp.resource("ui://widget/main.html")
def get_widget() -> str:
    return "<html>...</html>"

if __name__ == "__main__":
    mcp.run(transport="streamable-http", port=8000)
```

### TypeScript Setup

Install the MCP TypeScript SDK:

```bash
npm install @modelcontextprotocol/sdk zod
```

**Minimal server structure:**
```typescript
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { z } from "zod";

const server = new Server(
  { name: "server-name", version: "1.0.0" },
  { capabilities: { tools: {}, resources: {} } }
);

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [{
    name: "example_tool",
    description: "Tool description",
    inputSchema: { type: "object", properties: { query: { type: "string" } } }
  }]
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "example_tool") {
    return { content: [{ type: "text", text: "Result" }] };
  }
});
```

## Response Structure

Tool responses include three layers:

| Field | Visibility | Purpose |
|-------|------------|---------|
| `structuredContent` | Model + Widget | Concise JSON the model reads for narration |
| `content` | Model + Widget | Text/image content for display |
| `_meta` | Widget only | Rich data exclusively for UI rendering |

**Example response:**
```python
return {
    "structuredContent": {"status": "success", "count": 42},
    "content": [{"type": "text", "text": "Found 42 items"}],
    "_meta": {
        "items": [...],  # Full data for widget
        "openai/outputTemplate": "ui://widget/list.html"
    }
}
```

## Server Configuration Best Practices

### Port and Host

- Use port 8000 by default for local development
- Bind to `0.0.0.0` for container deployments
- Bind to `127.0.0.1` for local-only access

### HTTPS Requirements

ChatGPT requires HTTPS for all production MCP servers. Use ngrok during development:

```bash
ngrok http 8000
```

### Environment Variables

Store sensitive configuration in environment variables:

```python
import os
API_KEY = os.environ.get("API_KEY")
DATABASE_URL = os.environ.get("DATABASE_URL")
```

### Error Handling

Return structured errors the model can understand:

```python
@mcp.tool()
def safe_tool(param: str) -> dict:
    try:
        result = process(param)
        return {"success": True, "data": result}
    except ValueError as e:
        return {"success": False, "error": str(e)}
```

## Project Structure

Recommended directory layout for MCP server projects:

```
my-mcp-server/
├── server.py          # or server.ts
├── tools/
│   ├── __init__.py
│   └── my_tool.py
├── widgets/
│   └── main.html
├── requirements.txt   # or package.json
└── .env.example
```

## Additional Resources

### Reference Files

For detailed SDK documentation and patterns:
- **`references/python-sdk.md`** - Python SDK detailed reference
- **`references/typescript-sdk.md`** - TypeScript SDK detailed reference
- **`references/transport-comparison.md`** - Transport protocol comparison

### Example Files

Working server examples in `examples/`:
- **`examples/minimal-server.py`** - Minimal Python MCP server
- **`examples/minimal-server.ts`** - Minimal TypeScript MCP server

### Official Documentation

- Apps SDK Docs: https://developers.openai.com/apps-sdk/
- MCP Specification: https://modelcontextprotocol.io/specification/
- Python SDK: https://github.com/modelcontextprotocol/python-sdk
- TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk

Related Skills

MCP Architecture Expert

16
from diegosouzapw/awesome-omni-skill

Design and implement Model Context Protocol servers for standardized AI-to-data integration with resources, tools, prompts, and security best practices

architecture-paradigm-pipeline

16
from diegosouzapw/awesome-omni-skill

Consult this skill when designing data pipelines or transformation workflows. Use when data flows through fixed sequence of transformations, stages can be independently developed and tested, parallel processing of stages is beneficial. Do not use when selecting from multiple paradigms - use architecture-paradigms first. DO NOT use when: data flow is not sequential or predictable. DO NOT use when: complex branching/merging logic dominates.

architecture-advisor

16
from diegosouzapw/awesome-omni-skill

Helps solo developers with AI agents choose optimal architecture (monolithic/microservices/hybrid)

agent-native-architecture

16
from diegosouzapw/awesome-omni-skill

Build applications where agents are first-class citizens. Use this skill when designing autonomous agents, creating MCP tools, implementing self-modifying systems, or building apps where features are outcomes achieved by agents operating in a loop.

agent-architecture

16
from diegosouzapw/awesome-omni-skill

Use when designing or implementing AI agent systems. Covers tool-using agents with mandatory guardrails, SSE streaming (FastAPI → Next.js via Vercel AI SDK v6), LangGraph stateful multi-agent graphs, episodic memory via pgvector, MCP overview, and production failure modes with anti-pattern/fix code pairs.

u07820-attention-management-architecture-for-personal-finance-management

16
from diegosouzapw/awesome-omni-skill

Build and operate the "Attention Management Architecture for personal finance management" capability for personal finance management. Use when this exact capability is required by autonomous or human-guided missions.

solidstart-advanced-server

16
from diegosouzapw/awesome-omni-skill

SolidStart advanced server: getRequestEvent for request context, static assets handling, returning responses, request events and nativeEvent access.

server-management

16
from diegosouzapw/awesome-omni-skill

Server management principles and decision-making. Process management, monitoring strategy, and scaling decisions. Teaches thinking, not commands.

quarkus-mcp-server-sse

16
from diegosouzapw/awesome-omni-skill

Quarkus and MCP Server with HTTP SSE transport development standards and instructions Triggers on: *

php-mcp-server

16
from diegosouzapw/awesome-omni-skill

Best practices for building Model Context Protocol servers in PHP using the official PHP SDK with attribute-based discovery and multiple transport options Triggers on: **/*.php

mcpserver

16
from diegosouzapw/awesome-omni-skill

Migrates an MCP server with interactive widgets from the OpenAI Apps SDK (window.openai, text/html+skybridge) to the MCP Apps standard (@modelcontextprotocol/ext-apps), covering server-side and client-side changes.

java-mcp-server

16
from diegosouzapw/awesome-omni-skill

Best practices and patterns for building Model Context Protocol (MCP) servers in Java using the official MCP Java SDK with reactive streams and Spring integration. Triggers on: **/*.java, **/pom.xml, **/build.gradle, **/build.gradle.kts