[opencode 12일 집중 — 터미널 네이티브 AI 코딩 에이전트 완전 정복] 9/12화: opencode MCP 서버 연동 — 외부 도구·데이터 확장 실전 가이드

이 글은 「opencode 12일 집중」 9일차로, opencode에 MCP 서버를 연동해 외부 도구와 데이터 소스를 확장하는 방법을 다룹니다.

어제 8일차에서는 커스텀 슬래시 커맨드와 Named Arguments로 반복 작업을 자동화하는 방법을 다뤘습니다. 오늘은 opencode의 능력을 근본적으로 확장하는 열쇠, MCP(Model Context Protocol) 서버 연동을 다룹니다.

opencode가 코드만 읽고 쓸 수 있다면?

지금까지 opencode는 파일을 읽고, 셸 명령을 실행하고, LSP로 코드를 탐색했습니다. 강력하지만 한계가 있습니다. 사내 위키에서 API 스펙을 찾아오거나, Jira 티켓을 조회하거나, 데이터베이스 스키마를 실시간으로 확인하는 건 내장 툴만으로는 불가능합니다. MCP는 이 벽을 깨는 프로토콜입니다.

오늘의 핵심 3가지

• MCP 개념 — Model Context Protocol이 무엇이고, 왜 AI 에이전트 생태계의 USB-C라 불리는지
• opencode 설정 — opencode.json에 MCP 서버를 등록하고 연결하는 구체적 방법
• 실전 시나리오 — 사내 RAG·DB·API를 연동해 업무 맥락을 주입하는 패턴

MCP란 무엇인가

AI 에이전트의 USB-C

MCP(Model Context Protocol)는 Anthropic이 2024년 말 공개한 오픈 표준입니다. AI 모델과 외부 도구·데이터 소스 사이의 통신 규격을 정의합니다. USB-C가 충전기·모니터·외장 드라이브를 하나의 포트로 연결하듯, MCP는 다양한 외부 시스템을 하나의 프로토콜로 AI에 연결합니다.

MCP 이전에는 각 AI 도구가 저마다의 플러그인 시스템을 가졌습니다. Claude의 Tool Use, OpenAI의 Function Calling, LangChain의 Tool 인터페이스 — 모두 비슷한 문제를 다른 방식으로 풀었습니다. MCP는 이 파편화를 표준으로 통합합니다.

MCP의 3가지 핵심 개념

MCP는 세 가지 주요 기능 단위로 나뉩니다.

• Tools(도구) — AI가 호출할 수 있는 함수입니다. DB 쿼리 실행, API 호출, 파일 변환 같은 액션을 수행합니다. opencode의 내장 툴(read, write, bash)과 같은 레벨에서 작동합니다.
• Resources(자원) — AI가 읽을 수 있는 데이터입니다. 사내 위키 문서, API 스펙, 환경 설정 같은 참조 정보를 제공합니다.
• Prompts(프롬프트) — 미리 정의된 프롬프트 템플릿입니다. 특정 작업에 최적화된 지시문을 MCP 서버가 제공합니다.

opencode에서 가장 많이 쓰이는 건 Tools입니다. MCP 서버가 제공하는 도구가 opencode의 도구 목록에 자동으로 추가되고, AI 모델이 필요할 때 호출합니다.

클라이언트-서버 구조

MCP는 클라이언트-서버 구조입니다. opencode가 MCP 클라이언트 역할을 하고, 외부 도구를 제공하는 프로그램이 MCP 서버입니다. 하나의 opencode 인스턴스에 여러 MCP 서버를 동시에 연결할 수 있습니다.

전송 방식은 두 가지입니다.

• stdio — MCP 서버를 자식 프로세스로 실행하고 표준입출력(stdin/stdout)으로 통신합니다. 로컬 도구에 적합합니다. 설정이 간단하고 네트워크가 필요 없습니다.
• sse(Server-Sent Events) — 원격 MCP 서버에 HTTP로 연결합니다. 사내 서버에서 MCP 서버를 운영할 때 사용합니다. 여러 개발자가 하나의 MCP 서버를 공유할 수 있습니다.

opencode에서 MCP 서버 설정하기

설정 파일 위치

MCP 서버 설정은 프로젝트 루트의 opencode.json에 작성합니다. 3일차에서 다룬 모델 설정과 같은 파일입니다.

{
  "provider": {
    "anthropic": {
      "apiKey": "env:ANTHROPIC_API_KEY"
    }
  },
  "model": {
    "big": "anthropic/claude-sonnet-4-20250514",
    "small": "anthropic/claude-sonnet-4-20250514"
  },
  "mcp": {
    "servers": {
      // 여기에 MCP 서버를 등록합니다
    }
  }
}

mcp.servers 아래에 서버 이름을 키로, 연결 정보를 값으로 지정합니다. 서버 이름은 자유롭게 정할 수 있지만, 용도를 알 수 있는 이름을 권장합니다.

stdio 방식 — 로컬 MCP 서버

가장 흔한 패턴입니다. MCP 서버를 npx, uvx, 또는 직접 실행 파일로 구동합니다.

{
  "mcp": {
    "servers": {
      "filesystem": {
        "type": "local",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"],
        "enabled": true
      }
    }
  }
}

각 필드의 의미입니다.

• type — "local"은 stdio 기반 로컬 프로세스를 뜻합니다.
• command — 실행할 명령어입니다. npx, uvx, node, python 등.
• args — 명령어에 전달할 인자 배열입니다.
• enabled — false로 설정하면 서버를 일시 비활성화할 수 있습니다.

환경 변수가 필요한 MCP 서버는 env 필드를 추가합니다.

{
  "mcp": {
    "servers": {
      "github": {
        "type": "local",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": "env:GITHUB_TOKEN"
        },
        "enabled": true
      }
    }
  }
}

"env:GITHUB_TOKEN" 구문은 시스템 환경 변수 GITHUB_TOKEN의 값을 참조합니다. API 키를 설정 파일에 직접 쓰지 않아도 됩니다.

SSE 방식 — 원격 MCP 서버

사내 서버에서 MCP 서버를 운영하고, 여러 개발자가 공유하는 경우에 사용합니다.

{
  "mcp": {
    "servers": {
      "company-rag": {
        "type": "remote",
        "url": "http://internal-server:3001/sse",
        "enabled": true
      }
    }
  }
}

type이 "remote"이고 url로 MCP 서버의 SSE 엔드포인트를 지정합니다. 이 방식은 MCP 서버가 이미 별도 프로세스로 실행 중이어야 합니다.

여러 MCP 서버 동시 연결

실무에서는 여러 MCP 서버를 동시에 사용하는 경우가 많습니다. opencode는 설정된 모든 MCP 서버에 동시 연결하고, 각 서버의 도구를 통합해 AI 모델에 노출합니다.

{
  "mcp": {
    "servers": {
      "filesystem": {
        "type": "local",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "./docs"],
        "enabled": true
      },
      "github": {
        "type": "local",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": "env:GITHUB_TOKEN"
        },
        "enabled": true
      },
      "postgres": {
        "type": "local",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-postgres",
                 "postgresql://readonly:password@localhost:5432/mydb"],
        "enabled": true
      }
    }
  }
}

이 설정 하나로 opencode는 파일시스템 탐색, GitHub 이슈 조회, PostgreSQL 스키마 확인을 모두 AI 도구로 사용할 수 있게 됩니다.

실전: MCP 서버 연동 따라 하기

실습 1 — 파일시스템 MCP 서버

가장 단순한 예제로 시작합니다. @modelcontextprotocol/server-filesystem은 지정된 디렉터리의 파일을 읽고 쓰는 도구를 제공합니다.

# 1. 프로젝트 루트에 opencode.json 설정 추가 (기존 설정에 mcp 섹션 병합)
cat opencode.json
# mcp.servers.filesystem 항목이 있는지 확인

# 2. opencode 실행
opencode

# 3. 세션에서 MCP 도구 확인
# AI에게 물어보세요:
# "현재 사용 가능한 MCP 도구를 알려줘"

# 4. MCP 도구 사용 테스트
# "docs 폴더의 파일 목록을 filesystem MCP로 확인해줘"

opencode가 시작되면 설정된 MCP 서버에 자동으로 연결합니다. 연결에 성공하면 MCP 서버가 제공하는 도구가 AI의 사용 가능 도구 목록에 추가됩니다. AI 모델은 대화 맥락에 따라 내장 툴과 MCP 도구 중 적절한 것을 자동으로 선택합니다.

실습 2 — GitHub MCP 서버

GitHub MCP 서버를 연결하면 이슈 조회, PR 정보 확인, 코드 검색을 AI 대화 안에서 바로 할 수 있습니다.

# 1. GitHub Personal Access Token 설정
export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"

# 2. opencode.json에 GitHub MCP 서버 추가
# (위 설정 예시 참조)

# 3. opencode 실행 후 테스트
opencode

# 세션에서:
# "이 저장소의 열린 이슈 목록을 보여줘"
# "PR #42의 변경 사항을 요약해줘"
# "#123 이슈에 코멘트를 달아줘: 수정 완료했습니다"

GitHub MCP 서버가 제공하는 주요 도구입니다.

• list_issues — 이슈 목록 조회
• get_issue — 특정 이슈 상세 조회
• create_issue — 이슈 생성
• list_pull_requests — PR 목록 조회
• get_pull_request_diff — PR diff 조회
• search_code — 코드 검색

코드를 수정하면서 관련 이슈를 확인하고, PR 정보를 참조하는 워크플로우가 하나의 터미널 안에서 완성됩니다.

실습 3 — PostgreSQL MCP 서버

데이터베이스 스키마를 참조하면서 코딩하는 것은 백엔드 개발의 일상입니다. PostgreSQL MCP 서버를 연결하면 AI가 실시간으로 테이블 구조를 확인합니다.

# opencode.json 설정
{
  "mcp": {
    "servers": {
      "postgres": {
        "type": "local",
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-postgres",
          "postgresql://readonly_user:password@localhost:5432/app_db"
        ],
        "enabled": true
      }
    }
  }
}

# opencode 세션에서:
# "users 테이블의 스키마를 확인해줘"
# "orders 테이블과 users 테이블의 관계를 분석해줘"
# "최근 7일간 주문 건수를 조회하는 쿼리를 작성해줘"

주의: 반드시 읽기 전용(readonly) 계정을 사용하세요. AI가 DROP TABLE이나 DELETE를 실행할 가능성은 낮지만, 원천 차단이 원칙입니다. 이 부분은 아래 보안 섹션에서 다시 강조합니다.

사내 시스템 연동 패턴

패턴 1 — 사내 RAG 연동

사내 문서 검색 시스템(RAG)을 MCP 서버로 감싸면, AI가 코딩하면서 사내 문서를 자동으로 참조합니다.

# 사내 RAG MCP 서버 예시 (Python, FastMCP 라이브러리 사용)

from mcp.server.fastmcp import FastMCP
import httpx

mcp = FastMCP("company-docs")

@mcp.tool()
async def search_docs(query: str, top_k: int = 5) -> str:
    """사내 문서에서 관련 내용을 검색합니다."""
    async with httpx.AsyncClient() as client:
        resp = await client.post(
            "http://internal-rag-api:8000/search",
            json={"query": query, "top_k": top_k}
        )
        results = resp.json()["results"]
        return "\n\n---\n\n".join(
            f"[{r['title']}]\n{r['content']}" for r in results
        )

@mcp.tool()
async def get_api_spec(service_name: str) -> str:
    """특정 서비스의 API 스펙을 조회합니다."""
    async with httpx.AsyncClient() as client:
        resp = await client.get(
            f"http://internal-rag-api:8000/specs/{service_name}"
        )
        return resp.json()["spec"]

if __name__ == "__main__":
    mcp.run()

이 MCP 서버를 opencode에 연결합니다.

{
  "mcp": {
    "servers": {
      "company-docs": {
        "type": "local",
        "command": "python",
        "args": ["./tools/mcp_rag_server.py"],
        "enabled": true
      }
    }
  }
}

이제 opencode 세션에서 “결제 API의 응답 형식을 확인해줘”라고 말하면, AI가 search_docs 도구를 호출해 사내 문서에서 관련 스펙을 찾아옵니다. 브라우저를 열고 위키를 검색할 필요가 없습니다.

패턴 2 — Jira/이슈 트래커 연동

Jira MCP 서버를 연결하면 티켓 내용을 보면서 코딩할 수 있습니다.

from mcp.server.fastmcp import FastMCP
import httpx

mcp = FastMCP("jira")

JIRA_BASE = "https://company.atlassian.net"
JIRA_TOKEN = "env:JIRA_API_TOKEN"
JIRA_EMAIL = "env:JIRA_EMAIL"

@mcp.tool()
async def get_ticket(ticket_id: str) -> str:
    """Jira 티켓의 상세 내용을 조회합니다."""
    async with httpx.AsyncClient() as client:
        resp = await client.get(
            f"{JIRA_BASE}/rest/api/3/issue/{ticket_id}",
            auth=(JIRA_EMAIL, JIRA_TOKEN)
        )
        issue = resp.json()
        return (
            f"제목: {issue['fields']['summary']}\n"
            f"상태: {issue['fields']['status']['name']}\n"
            f"설명: {issue['fields'].get('description', '없음')}"
        )

@mcp.tool()
async def list_my_tickets(status: str = "In Progress") -> str:
    """내게 할당된 티켓 목록을 조회합니다."""
    jql = f"assignee=currentUser() AND status='{status}'"
    async with httpx.AsyncClient() as client:
        resp = await client.get(
            f"{JIRA_BASE}/rest/api/3/search",
            params={"jql": jql, "maxResults": 10},
            auth=(JIRA_EMAIL, JIRA_TOKEN)
        )
        issues = resp.json()["issues"]
        return "\n".join(
            f"- {i['key']}: {i['fields']['summary']}" for i in issues
        )

if __name__ == "__main__":
    mcp.run()

“PROJ-456 티켓의 요구사항을 확인하고, 그에 맞게 UserService를 수정해줘” — 이런 자연어 요청이 가능해집니다. 티켓 조회 → 코드 수정 → 커밋 메시지에 티켓 번호 포함까지 한 흐름으로 처리됩니다.

패턴 3 — API 게이트웨이 연동

마이크로서비스 환경에서 다른 서비스의 API를 확인하면서 개발하는 패턴입니다.

from mcp.server.fastmcp import FastMCP
import httpx

mcp = FastMCP("api-gateway")

@mcp.tool()
async def call_internal_api(
    service: str,
    method: str,
    path: str,
    body: str = ""
) -> str:
    """사내 API를 호출합니다. 개발/스테이징 환경 전용."""
    base_urls = {
        "user-service": "http://user-svc.dev.internal:8080",
        "payment-service": "http://payment-svc.dev.internal:8080",
        "notification-service": "http://noti-svc.dev.internal:8080",
    }
    if service not in base_urls:
        return f"알 수 없는 서비스: {service}. 사용 가능: {list(base_urls.keys())}"

    url = f"{base_urls[service]}{path}"
    async with httpx.AsyncClient() as client:
        resp = await client.request(
            method=method.upper(),
            url=url,
            content=body if body else None,
            headers={"Content-Type": "application/json"} if body else {}
        )
        return f"Status: {resp.status_code}\nBody: {resp.text[:2000]}"

if __name__ == "__main__":
    mcp.run()

개발 환경의 API를 AI가 직접 호출해서 응답 형식을 확인하고, 그에 맞는 클라이언트 코드를 작성합니다. Swagger UI를 왔다 갔다 하는 시간이 줄어듭니다.

MCP 서버 관리 팁

서버 활성화/비활성화

모든 MCP 서버를 항상 켜놓을 필요는 없습니다. 사용하지 않는 MCP 서버는 enabled: false로 비활성화하면 opencode 시작 시 연결을 시도하지 않습니다.

{
  "mcp": {
    "servers": {
      "postgres": {
        "type": "local",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-postgres", "..."],
        "enabled": false
      }
    }
  }
}

MCP 서버가 많아지면 AI 모델에 전달되는 도구 목록도 길어집니다. 불필요한 도구가 많으면 모델이 잘못된 도구를 선택할 확률이 높아지고, 토큰 소모도 늘어납니다. 현재 작업에 필요한 서버만 활성화하는 습관을 들이세요.

프로젝트별 설정 분리

각 프로젝트의 opencode.json에 해당 프로젝트에 필요한 MCP 서버만 설정합니다. 프론트엔드 프로젝트에는 디자인 시스템 MCP를, 백엔드 프로젝트에는 DB MCP를 설정하는 식입니다.

# 프론트엔드 프로젝트의 opencode.json
{
  "mcp": {
    "servers": {
      "figma": { "type": "local", "command": "...", "enabled": true },
      "storybook": { "type": "local", "command": "...", "enabled": true }
    }
  }
}

# 백엔드 프로젝트의 opencode.json
{
  "mcp": {
    "servers": {
      "postgres": { "type": "local", "command": "...", "enabled": true },
      "redis": { "type": "local", "command": "...", "enabled": true },
      "company-docs": { "type": "remote", "url": "...", "enabled": true }
    }
  }
}

MCP 서버 개발 도구

자체 MCP 서버를 만들 때 유용한 도구들입니다.

• Python: mcp 패키지의 FastMCP — 데코레이터 기반으로 가장 빠르게 서버를 만들 수 있습니다.
• TypeScript: @modelcontextprotocol/sdk — 공식 SDK로 타입 안전한 서버를 작성합니다.
• MCP Inspector: npx @modelcontextprotocol/inspector — MCP 서버를 브라우저에서 테스트하는 디버깅 도구입니다.

# MCP Inspector로 서버 테스트
npx @modelcontextprotocol/inspector python ./tools/mcp_rag_server.py

# 브라우저에서 http://localhost:5173 접속
# → 도구 목록 확인, 직접 호출 테스트 가능

MCP Inspector는 opencode에 연결하기 전에 서버가 올바르게 동작하는지 확인하는 데 필수적입니다. 도구 이름, 파라미터, 반환값을 시각적으로 검증할 수 있습니다.

보안 고려사항

최소 권한 원칙

MCP 서버에 부여하는 권한은 최소한으로 제한합니다.

• DB 연결: 읽기 전용 계정을 사용합니다. SELECT만 허용하고 INSERT, UPDATE, DELETE, DROP을 차단합니다.
• 파일시스템: 필요한 디렉터리만 허용합니다. 루트(/)를 통째로 열지 마세요.
• API 토큰: 읽기 전용 스코프의 토큰을 발급합니다. GitHub PAT라면 repo:read만 부여합니다.
• 네트워크: 개발/스테이징 환경의 API만 연결합니다. 프로덕션 DB나 API에 직접 연결하지 마세요.

비밀 정보 관리

API 키, DB 비밀번호 같은 시크릿은 opencode.json에 직접 쓰지 않습니다.

# 나쁜 예 ❌
{
  "env": {
    "DB_PASSWORD": "super_secret_123"
  }
}

# 좋은 예 ✅
{
  "env": {
    "DB_PASSWORD": "env:DB_PASSWORD"
  }
}

env: 접두어로 시스템 환경 변수를 참조하거나, .env 파일을 사용하되 .gitignore에 반드시 추가합니다. opencode.json 자체를 Git에 커밋할 때 시크릿이 포함되어 있지 않은지 확인하세요.

MCP 서버 신뢰성

커뮤니티 MCP 서버를 사용할 때는 소스 코드를 확인합니다. MCP 서버는 로컬 머신에서 실행되므로, 악의적인 서버는 파일 시스템 접근이나 네트워크 요청을 수행할 수 있습니다.

• 공식 저장소(@modelcontextprotocol/*)의 서버를 우선 사용합니다.
• 서드파티 서버는 GitHub 스타 수, 최근 커밋, 이슈 대응을 확인합니다.
• 가능하면 MCP 서버 코드를 직접 읽어보세요. 대부분 수백 줄 이내로 짧습니다.

금융IT 실무 적용 — 익명 사례

A 금융사의 사내 규정 검색 MCP

어느 금융사 개발팀에서 MCP를 도입한 사례입니다. 이 팀은 금융 거래 시스템을 개발하면서, 수시로 사내 보안 규정과 금융감독원 전자금융감독규정을 참조해야 했습니다. 기존에는 사내 포털에서 규정을 검색하고, 관련 조항을 복사해서 코드 리뷰 근거로 붙여넣는 수작업이 반복됐습니다.

이 팀이 구축한 MCP 서버의 구조입니다.

# 금융 규정 검색 MCP 서버 (개념 수준, 실제 코드 아님)

@mcp.tool()
async def search_regulation(query: str, category: str = "all") -> str:
    """사내 보안 규정 및 금융감독 규정을 검색합니다.
    category: security(보안), privacy(개인정보), finance(금융감독), all
    """
    # 사내 RAG 시스템 호출 (벡터 DB + 규정 원문)
    results = await rag_client.search(query, category, top_k=3)
    return format_results(results)

@mcp.tool()
async def check_compliance(code_snippet: str) -> str:
    """코드 스니펫이 사내 보안 규정에 부합하는지 간이 검토합니다.
    주의: 이 결과는 참고용이며, 공식 보안 심의를 대체하지 않습니다.
    """
    # 규정 기반 룰 체크 (암호화 알고리즘, 로깅 정책, 접근제어 등)
    violations = await compliance_checker.check(code_snippet)
    return format_violations(violations)

실제 사용 흐름입니다. 개발자가 opencode에서 결제 모듈을 수정하면서 “이 암호화 방식이 전자금융감독규정에 맞는지 확인해줘”라고 요청합니다. AI가 MCP 도구로 규정을 검색하고, 현재 코드와 대조해서 “AES-128은 최소 요건을 충족하나, 규정 제15조에 따라 AES-256 이상을 권장합니다”와 같은 맥락 있는 답변을 돌려줍니다.

이 팀이 공유한 운영 원칙입니다.

• MCP 서버는 망분리 내부(개발망)에서만 구동합니다. 외부 LLM API로 규정 내용이 전송되지 않도록 로컬 모델을 사용하거나, AI 모델에 전달되는 도구 결과에서 핵심 조항 번호만 반환하고 원문은 생략합니다.
• MCP 서버 접근 로그를 남깁니다. 누가, 언제, 어떤 규정을 조회했는지 감사 추적이 가능해야 합니다.
• AI의 규정 판단은 참고용입니다. 최종 컴플라이언스 판단은 반드시 보안팀/컴플라이언스팀의 공식 심의를 거칩니다.

이 사례의 핵심 교훈은 MCP가 “코딩 도우미”를 “업무 맥락을 이해하는 도우미”로 격상시킨다는 점입니다. 도메인 특화 지식을 주입함으로써, 범용 AI 모델이 사내 전문가에 가까운 조언을 하게 됩니다.

인기 MCP 서버 카탈로그

opencode에서 바로 쓸 수 있는 주요 MCP 서버를 정리합니다.

공식 서버 (@modelcontextprotocol/)

• server-filesystem — 파일 읽기/쓰기/검색. 허용 디렉터리 제한 기능 내장.
• server-github — 이슈, PR, 코드 검색, 저장소 관리.
• server-postgres — PostgreSQL 스키마 조회, 쿼리 실행 (읽기 전용 권장).
• server-sqlite — SQLite DB 조회. 로컬 프로토타이핑에 유용.
• server-memory — 지식 그래프 기반 영속 메모리. 세션 간 정보 유지.
• server-brave-search — Brave 웹 검색 API. 최신 정보 조회.
• server-puppeteer — 브라우저 자동화. 웹 페이지 스크린샷, 콘솔 로그 확인.

커뮤니티 인기 서버

• mcp-server-fetch — HTTP 요청 전송. REST API 테스트에 활용.
• mcp-server-docker — Docker 컨테이너 관리. 컨테이너 상태 확인, 로그 조회.
• mcp-server-kubernetes — K8s 클러스터 조회. Pod 상태, 로그 확인.
• mcp-server-slack — Slack 메시지 조회/전송. 팀 커뮤니케이션 연동.
• mcp-server-notion — Notion 페이지 검색/읽기. 문서 참조.

자체 개발 시 FastMCP 시작 템플릿

# pip install mcp
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-custom-tools")

@mcp.tool()
def greet(name: str) -> str:
    """사용자에게 인사합니다."""
    return f"안녕하세요, {name}님!"

@mcp.tool()
def calculate_tax(amount: float, rate: float = 0.1) -> str:
    """세금을 계산합니다."""
    tax = amount * rate
    return f"금액: {amount:,.0f}원, 세율: {rate*100:.1f}%, 세금: {tax:,.0f}원"

if __name__ == "__main__":
    mcp.run()  # stdio 모드로 실행

# opencode.json 에 등록
{
  "mcp": {
    "servers": {
      "my-tools": {
        "type": "local",
        "command": "python",
        "args": ["./tools/my_mcp_server.py"],
        "enabled": true
      }
    }
  }
}

@mcp.tool() 데코레이터 하나로 함수가 MCP 도구가 됩니다. 함수의 docstring이 도구 설명으로, 타입 어노테이션이 파라미터 스키마로 자동 변환됩니다. 10분이면 첫 MCP 서버를 만들 수 있습니다.

MCP 연동 아키텍처 패턴

패턴 A — 직접 연동 (소규모 팀)

각 개발자의 로컬에서 MCP 서버를 실행합니다. 설정이 간단하고, 추가 인프라가 필요 없습니다.

opencode (로컬)
  ├── stdio → filesystem MCP (로컬)
  ├── stdio → postgres MCP (로컬 → 개발 DB)
  └── stdio → custom RAG MCP (로컬 → 사내 RAG API)

패턴 B — 공유 MCP 서버 (중규모 팀)

사내 서버에서 MCP 서버를 운영하고, 개발자들이 SSE로 연결합니다. MCP 서버 업데이트를 중앙에서 관리할 수 있습니다.

개발자 A의 opencode ──┐
개발자 B의 opencode ──┼── SSE ──→ 사내 MCP 서버 (Docker)
개발자 C의 opencode ──┘               ├── 사내 RAG
                                       ├── Jira 연동
                                       └── DB 스키마 조회

패턴 C — 게이트웨이 패턴 (엔터프라이즈)

MCP 게이트웨이를 두고, 인증·인가·감사 로그를 중앙에서 처리합니다. 금융·의료 같은 규제 산업에 적합합니다.

opencode ── SSE ──→ MCP Gateway (인증·로깅)
                         ├── 규정 검색 MCP
                         ├── 감사 로그 MCP
                         └── 내부 API MCP
                              └── (모든 호출에 사용자 ID, 타임스탬프 기록)

팀 규모와 보안 요구사항에 따라 적절한 패턴을 선택하세요. 처음에는 패턴 A로 시작하고, 팀이 커지면 패턴 B로 전환하는 것이 자연스럽습니다.

Gotcha 미니 코너

MCP 서버가 많으면 느려진다

MCP 서버를 5개, 10개 연결하고 싶은 유혹이 있습니다. 하지만 MCP 서버가 늘어날수록 두 가지 비용이 증가합니다.

첫째, 시작 시간. opencode가 실행될 때 모든 MCP 서버에 연결을 시도합니다. 서버마다 프로세스를 띄우고 핸드셰이크를 완료해야 하므로, 서버가 많을수록 opencode 시작이 느려집니다. 특히 npx 기반 서버는 npm 패키지를 다운로드하는 시간이 추가됩니다.

둘째, 토큰 소모. 각 MCP 서버가 제공하는 도구 목록(이름, 설명, 파라미터 스키마)이 AI 모델의 시스템 프롬프트에 포함됩니다. 서버 10개 × 도구 5개 = 50개 도구의 스키마가 매 요청에 들어갑니다. 이는 수천 토큰을 차지하며, 응답 품질에도 영향을 줍니다. 모델이 50개 도구 중 하나를 골라야 하니 잘못된 도구를 선택할 확률도 올라갑니다.

해결책: 현재 작업에 필요한 서버만 enabled: true로 켜세요. DB 작업할 때는 DB MCP만, 프론트엔드 작업할 때는 디자인 MCP만 활성화하는 식입니다. 3개 이하가 가장 쾌적합니다.

오늘의 실습 정리

오늘 다룬 내용을 하나의 완전한 설정으로 정리합니다.

# opencode.json — MCP 연동 실전 설정 예시

{
  "provider": {
    "anthropic": {
      "apiKey": "env:ANTHROPIC_API_KEY"
    }
  },
  "model": {
    "big": "anthropic/claude-sonnet-4-20250514",
    "small": "anthropic/claude-sonnet-4-20250514"
  },
  "mcp": {
    "servers": {
      "github": {
        "type": "local",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": "env:GITHUB_TOKEN"
        },
        "enabled": true
      },
      "postgres": {
        "type": "local",
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-postgres",
          "postgresql://readonly:pass@localhost:5432/dev_db"
        ],
        "enabled": false
      },
      "company-docs": {
        "type": "local",
        "command": "python",
        "args": ["./tools/mcp_rag_server.py"],
        "enabled": false
      }
    }
  }
}

# 터미널에서 실행
export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxxxxxxxxx"

# opencode 시작 — MCP 서버 자동 연결
opencode

# 세션에서 테스트:
# "사용 가능한 MCP 도구 목록을 보여줘"
# "이 저장소의 최근 이슈 5개를 보여줘"

GitHub MCP만 활성화한 상태로 시작하고, DB나 사내 문서 검색이 필요할 때 opencode.json에서 enabled를 true로 바꾸고 opencode를 재시작하면 됩니다.

내일 예고

10일차에서는 opencode의 비대화형 모드와 자동화를 다룹니다. opencode run으로 스크립트처럼 실행하고, opencode serve로 HTTP 서버를 띄워 다른 시스템과 통합하는 방법 — CI/CD 파이프라인에 AI 코딩 에이전트를 끼워넣는 실전입니다.

---