API Contract로서의 MCP 도구: 에이전트가 무엇을 할 수 있는지 문서화하기
몇 달 전 우리는 API Contracts를 출시했습니다. OpenAPI, gRPC, GraphQL, AsyncAPI 명세를 그것을 구현하고 소비하는 C4 요소에 직접 연결하는 기능입니다. 발상은 단순했습니다. 인터페이스의 정확하고 기계가 읽을 수 있는 설명은 아무도 갱신하지 않는 Notion 페이지가 아니라 아키텍처 안에 있어야 한다는 것입니다.
아직 다루지 않은 인터페이스가 하나 남아 있었습니다. 가장 새로운 것. 여러분의 서비스가 다른 서비스가 아니라 점점 더 AI 에이전트에게 노출하는 것 ── MCP입니다.
MCP 서버는 일련의 도구를 게시합니다. 각각 이름, 설명, 그리고 입력을 위한 JSON Schema를 가집니다. 이것은 계약입니다. 에이전트가 여러분의 시스템에 대해 무엇을 해도 되는지를 결정하는 계약입니다. 그리고 오늘까지 그것은 아키텍처 문서에서 완전히 보이지 않았습니다.
이제는 아닙니다. MCP는 이제 Archyl의 일급 API Contract 유형입니다 ── HTTP, gRPC, GraphQL, AsyncAPI에 이은 다섯 번째입니다.
어려운 점: MCP 도구는 파일 안에 존재하지 않는다
다른 네 가지 계약 유형은 하나의 전제를 공유합니다 ── 저장소에 명세 파일이 있다는 것입니다. openapi.yaml. schema.graphql. Archyl을 그것에 가리키면 우리가 렌더링합니다.
MCP는 이를 깨뜨립니다. MCP 서버의 도구는 코드 안에서 정의되며, 완전하고 권위 있는 목록은 클라이언트가 tools/list를 호출하여 각 도구의 스키마를 돌려받는 런타임에만 존재합니다. 가리킬 수 있는 보편적인 mcp.yaml은 없습니다.
그래서 두 가지 진입로를 만들었습니다.
MCP 계약을 추가하는 두 가지 방법
붙여넣기. 이미 tools/list 출력이 있다면 붙여넣으세요. Archyl이 그것을 검증하고 각 도구 ── 설명과 입력 매개변수를 읽기 쉬운 표로 렌더링합니다.
또는 그냥 URL을 주세요. MCP 서버가 어디 있는지 Archyl에 알려주고, 필요하면 액세스 토큰을 (헤더 또는 쿼리 매개변수로) 추가한 뒤 도구 검색을 클릭하세요. Archyl이 연결하고 핸드셰이크를 수행하여 모든 도구와 매개변수를 자동으로 가져옵니다. 복사-붙여넣기도, 손으로 관리하는 파일도 없습니다.
라이브 검색이 동작하는 방식 ── 그리고 왜 안전한가
검색은 우리 서버가 아니라 여러분의 브라우저 안에서 일어납니다. 도구 검색을 클릭하면 여러분의 브라우저가 MCP 서버와 직접 대화합니다.
이 선택은 중요합니다:
- 토큰은 결코 브라우저를 떠나지 않습니다. Archyl은 검색된 도구와 연결 정보 ── URL, 전송 방식, 토큰이 들어가는 위치 ── 를 저장하지만, 토큰 자체는 결코 저장하지 않습니다.
- 서버 측에서 여러분의 네트워크에 접근하지 않습니다. 호출이 여러분의 머신에서 시작되므로, 다른 사람의 내부 서비스로 향하게 할 방법이 없습니다. SSRF 계열의 위험 전체가 여기에는 그저 존재하지 않습니다.
- localhost와 사설 서버에도 도달합니다. 노트북이나 네트워크 안에서 실행되는 서버를 테스트하나요? 여러분의 브라우저가 그것을 볼 수 있으니 동작합니다.
유일한 절충점은 CORS입니다. 서드파티 서버는 여러분의 브라우저가 응답을 읽을 수 있도록 Archyl의 오리진을 허용해야 합니다. 여러분이 관리하는 서버라면 설정 한 줄이면 되고, 그 외에는 붙여넣기 옵션이 언제나 있습니다.
다른 모든 계약처럼 아키텍처에 연결됨
일단 들어오면 MCP 계약은 다른 계약과 똑같이 동작합니다. 서버를 호스팅하는 container나 컴포넌트에 연결하세요. 각 도구와 그 입력 스키마를 둘러보세요. 서버가 바뀌면 다시 검색하세요. REST 및 GraphQL 계약 옆에 표시됩니다. 그것을 호출하는 에이전트에게는 똑같이 실재하는 API이기 때문입니다.
이는 여러분의 MCP 계약을 진정으로 새로운 것으로 바꿉니다. 시스템의 특정 부분에 대해 AI 에이전트가 무엇을 해도 되는지의 지도 ── 문서화되고, 연결되고, 검토 가능한 것입니다.
우리 자신에게도 사용합니다
Archyl 자체가 MCP 서버입니다 ── Claude Code, Cursor, 또는 어떤 MCP 클라이언트에서든 아키텍처를 조작할 수 있게 해주는 178개의 도구가 있습니다. 우리가 처음 만든 MCP 계약은 우리 자신의 것이었습니다. Archyl을 자신의 엔드포인트로 가리키고, 178개 도구를 모두 검색하고, 플랫폼에 연결했습니다. 우리의 에이전트 표면은 이제 스스로를 문서화합니다.
사용해 보세요
아무 프로젝트나 열고 API Contracts로 이동해 새로 만들고 MCP를 선택하세요. tools/list를 붙여넣거나 URL을 입력하고 도구 검색을 누르세요.
여러분의 서비스는 이미 에이전트와 대화하고 있습니다. 이제 여러분의 아키텍처가 그 대화 내용을 압니다.