2nd/10_Wiki/Topic_Programming/Coding/AI_MCP_Integration_Patterns.md

id, title, category, status, source_trust_level, verification_status, created_at, updated_at, tags, tech_stack, applied_in, aliases

id	title	category	status	source_trust_level	verification_status	created_at	updated_at	tags	tech_stack	applied_in	aliases
ai-mcp-integration-patterns	MCP — Model Context Protocol / Tool Server	Coding	draft	B	conceptual	2026-05-09	2026-05-09	ai mcp llm vibe-coding	language applicable_to TS / MCP SDK Backend		MCP Model Context Protocol Anthropic tool server resource prompts

MCP (Model Context Protocol)

Anthropic 표준 — LLM 이 tool / resource / prompts 를 통일된 방식으로 사용. Claude Desktop, Cursor, Cline, IDE 통합 의 표준. JSON-RPC 기반, stdio / HTTP+SSE.

📖 핵심 개념

• Server: tool / resource / prompts 제공.
• Client: LLM 앱 (Claude Desktop, IDE).
• Tools: 함수 (action).
• Resources: 데이터 (file / db).
• Prompts: 재사용 prompt template.

💻 코드 패턴

MCP Server (TS, stdio)

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
  ListResourcesRequestSchema,
  ReadResourceRequestSchema,
} from '@modelcontextprotocol/sdk/types.js';

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

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: 'search_orders',
      description: 'Search orders by customer email',
      inputSchema: {
        type: 'object',
        properties: { email: { type: 'string' } },
        required: ['email'],
      },
    },
  ],
}));

server.setRequestHandler(CallToolRequestSchema, async (req) => {
  if (req.params.name === 'search_orders') {
    const orders = await db.orders.findByEmail(req.params.arguments.email);
    return { content: [{ type: 'text', text: JSON.stringify(orders) }] };
  }
  throw new Error('unknown tool');
});

const transport = new StdioServerTransport();
await server.connect(transport);

Run

node dist/server.js

Client config (Claude Desktop)

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "acme": {
      "command": "node",
      "args": ["/path/to/server.js"],
      "env": { "DB_URL": "postgres://..." }
    }
  }
}

→ Claude 재시작 → tool 자동 인식.

Resources (data exposure)

server.setRequestHandler(ListResourcesRequestSchema, async () => ({
  resources: [
    { uri: 'acme://users', name: 'Users', mimeType: 'application/json' },
    { uri: 'acme://orders/recent', name: 'Recent orders', mimeType: 'application/json' },
  ],
}));

server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
  if (req.params.uri === 'acme://users') {
    return { contents: [{ uri: req.params.uri, mimeType: 'application/json', text: JSON.stringify(await db.users.list()) }] };
  }
  throw new Error('not found');
});

Prompts (reusable template)

server.setRequestHandler(ListPromptsRequestSchema, async () => ({
  prompts: [
    { name: 'analyze-customer', description: 'Summarize a customer', arguments: [{ name: 'email', required: true }] },
  ],
}));

server.setRequestHandler(GetPromptRequestSchema, async (req) => {
  if (req.params.name === 'analyze-customer') {
    return {
      messages: [{
        role: 'user',
        content: { type: 'text', text: `Summarize ${req.params.arguments?.email}'s purchase history.` },
      }],
    };
  }
});

HTTP + SSE transport

import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';

app.get('/sse', async (req, res) => {
  const transport = new SSEServerTransport('/messages', res);
  await server.connect(transport);
});

app.post('/messages', (req, res) => transport.handlePostMessage(req, res));

→ 멀티 client / cloud-deployed.

Auth (HTTP)

• OAuth: 사용자가 server 에 인증.
• Bearer: API key.
• TLS + CORS.

Capabilities

{ "tools": {}, "resources": { "subscribe": true }, "prompts": {}, "sampling": {} }

• Sampling: server 가 LLM 에 추가 호출 요청.
• Subscribe: resource 변경 알림.

Common MCP servers (커뮤니티)

• @modelcontextprotocol/server-filesystem
• @modelcontextprotocol/server-github
• @modelcontextprotocol/server-postgres
• 자체 = 회사 내 도구 wrap.

디버깅

# stdio 의 JSON-RPC trace
MCP_DEBUG=true node server.js

// Inspector
npx @modelcontextprotocol/inspector node server.js

🤔 의사결정 기준

사용	추천
Claude Desktop / Cursor 통합	MCP server
회사 내 코딩 도우미	MCP + private tools
Public API → AI tool	OpenAI tool / function calling
프롬프트 템플릿 공유	MCP prompts
Cloud-hosted multi-user	MCP HTTP+SSE
LangChain / LlamaIndex	tool wrapper (직접)

❌ 안티패턴

• Tool description 빈약: LLM 이 못 고름.
• Tool 가 sensitive 작업 confirm 없이: HITL 필요.
• PII resource 그대로 expose: filter / mask.
• Tool error 그대로 throw: LLM 이 복구 못 함. content + isError.
• Sync long task: timeout. async + status.
• Auth 없는 prod HTTP: 누구나 호출.
• Schema 자주 변경: 등록된 tool descrip 깨짐.

🤖 LLM 활용 힌트

• 회사 도구 = MCP server 로 wrap → 모든 LLM 클라이언트 호환.
• Tool 명확 descrip + JSON schema 작게.
• Sensitive = HITL or audit.

🔗 관련 문서

• AI_Function_Calling_Deep
• AI_Agentic_Patterns
• Backend_Webhook_Patterns