MCP와 에이전트 간 프로토콜

// .well-known/mcp.json — 실전 예시
{
  "name": "billing-mcp",
  "version": "2.1.0",
  "description": "고객 청구, 결제, 환불 관리 도구 모음",
  "homepage": "https://internal.example.com/billing-mcp",
  "tools": [
    {
      "name": "get_invoice",
      "description": "고객 ID와 기간으로 청구서를 조회합니다",
      "inputSchema": {
        "type": "object",
        "properties": {
          "customerId": { "type": "string" },
          "month": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" }
        },
        "required": ["customerId"]
      }
    },
    {
      "name": "create_refund",
      "description": "청구서에 대한 환불을 생성합니다",
      "inputSchema": {
        "type": "object",
        "properties": {
          "invoiceId": { "type": "string" },
          "amount": { "type": "number" },
          "reason": { "type": "string" }
        },
        "required": ["invoiceId", "amount"]
      }
    }
  ],
  "resources": [
    { "name": "billing-policy", "uri": "billing://policy", "mimeType": "text/markdown" },
    { "name": "pricing-table", "uri": "billing://pricing/2026", "mimeType": "application/json" }
  ],
  "auth": {
    "type": "oauth2",
    "authorizationUrl": "https://auth.example.com/authorize",
    "tokenUrl": "https://auth.example.com/token",
    "scopes": {
      "billing:read": "청구서 조회",
      "billing:write": "환불 생성, 청구서 수정"
    }
  },
  "transport": ["streamable-http"],
  "endpoint": "https://billing-mcp.example.com/mcp",
  "rateLimit": { "requestsPerMinute": 120 },
  "contacts": [{ "name": "billing-team", "email": "billing@example.com" }]
}

// .well-known/agent.json — 실전 예시
{
  "name": "billing-agent",
  "description": "고객 청구, 결제 분석, 환불 처리를 담당하는 전문 에이전트",
  "url": "https://billing-agent.example.com/a2a",
  "version": "1.2.0",
  "protocolVersion": "1.0.0",
  "skills": [
    {
      "id": "invoice-lookup",
      "name": "청구서 조회 및 분석",
      "description": "고객의 청구서를 조회하고 이상 항목을 분석합니다",
      "tags": ["billing", "invoice", "analysis"],
      "examples": [
        "고객 C-5678의 3월 청구서를 확인해 주세요",
        "지난 분기 청구 이상 항목을 분석해 주세요"
      ]
    },
    {
      "id": "refund-processing",
      "name": "환불 처리",
      "description": "환불 요청을 검증하고 처리합니다. 사용자 승인이 필요할 수 있습니다",
      "tags": ["billing", "refund"],
      "examples": [
        "청구서 INV-1234에 대해 부분 환불을 진행해 주세요"
      ]
    }
  ],
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "stateTransitions": ["input_required", "auth_required"]
  },
  "auth": [
    {
      "type": "oauth2",
      "authorizationUrl": "https://auth.example.com/authorize",
      "tokenUrl": "https://auth.example.com/token",
      "scopes": ["billing:read", "billing:write"]
    },
    {
      "type": "apiKey",
      "headerName": "X-API-Key",
      "description": "내부 서비스 간 통신용 API 키"
    }
  ]
}

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { z } from "zod";

const server = new McpServer({
  name: "billing-mcp",
  version: "1.0.0",
});

// Tool 정의: 청구서 조회
server.tool(
  "get_invoice",
  "고객의 청구서를 조회합니다",
  { customerId: z.string(), month: z.string().optional() },
  async ({ customerId, month }) => {
    const invoice = await db.invoices.find({ customerId, month });
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({
            id: invoice.id,
            amount: invoice.amount,
            status: invoice.status,
            dueDate: invoice.dueDate,
          }),
        },
      ],
    };
  }
);

// Resource 정의: 결제 정책 문서
server.resource("billing-policy", "billing://policy", async (uri) => ({
  contents: [
    {
      uri: uri.href,
      mimeType: "text/markdown",
      text: "## 환불 정책\n- 결제 후 7일 이내 전액 환불 가능\n...",
    },
  ],
}));

// Streamable HTTP transport로 서버 시작
const transport = new StreamableHTTPServerTransport({ endpoint: "/mcp" });
await server.connect(transport);

# 1. Agent Card 조회 — 에이전트의 역량과 인증 방식 확인
GET https://billing-agent.example.com/.well-known/agent.json

# 2. 태스크 생성 — 작업 위임
POST https://billing-agent.example.com/a2a
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "tasks/send",
  "id": "req-001",
  "params": {
    "id": "task-abc-123",
    "message": {
      "role": "user",
      "parts": [
        {
          "type": "text",
          "text": "고객 C-5678의 3월 청구서를 확인하고 이상이 있으면 보고해 주세요"
        }
      ]
    }
  }
}

# 3. 태스크 상태 조회 — 진행 상황 확인
POST https://billing-agent.example.com/a2a
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "tasks/get",
  "id": "req-002",
  "params": {
    "id": "task-abc-123"
  }
}

# 응답 예시 (working 상태)
{
  "jsonrpc": "2.0",
  "id": "req-002",
  "result": {
    "id": "task-abc-123",
    "status": { "state": "working" },
    "artifacts": []
  }
}

# 4. 완료 후 결과 수신
{
  "jsonrpc": "2.0",
  "id": "req-003",
  "result": {
    "id": "task-abc-123",
    "status": { "state": "completed" },
    "artifacts": [
      {
        "name": "billing-report",
        "parts": [
          { "type": "text", "text": "C-5678 고객 3월 청구서: 정상. 총액 ₩1,250,000" }
        ]
      }
    ]
  }
}

// 에러 처리 패턴 예시: A2A 태스크 호출 with retry
async function sendA2ATask(
  endpoint: string,
  task: A2ATaskRequest,
  maxRetries = 3
): Promise<A2ATaskResponse> {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(endpoint, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${await getValidToken()}`,
        },
        body: JSON.stringify(task),
        signal: AbortSignal.timeout(30_000),
      });

      if (response.status === 401) {
        await refreshAuthToken();
        continue; // 토큰 갱신 후 재시도
      }

      if (!response.ok) {
        throw new Error(`A2A error: ${response.status}`);
      }

      return await response.json();
    } catch (error) {
      if (attempt === maxRetries) throw error;
      await delay(Math.pow(2, attempt) * 1000); // exponential backoff
    }
  }
  throw new Error("Max retries exceeded");
}