MCP 통합
Anyy는 프로필과 프로젝트 구성으로 로컬 stdio 명령·원격 HTTP MCP 서버에 연결합니다. 각 서버에는 자체 활성 설정, 연결 구성, 도구 노출이 있습니다. 추가는 기본적으로 활성 지연 구성을 저장하며 점검하거나 도구 목록 선택을 묻지 않습니다. 비활성 저장은 --disable을 쓰세요.
연결 사전 요건
지원 전송은 stdio와 Streamable HTTP(http)입니다. 별도 sse는 거부하지만 Streamable HTTP의 일부인 이벤트 스트림은 가능합니다. 루프백 HTTP 외 원격은 HTTPS여야 합니다.
stdio 실행 파일·의존성은 Anyy 호스트에 설치하세요. npx에는 해당 호스트 Node.js/npm이 필요하며 Anyy가 번들·설치하지 않습니다. PATH·HOME 등 제한 환경만 상속하므로 나머지는 서버 env로 명시하세요. HTTP는 로컬 Node.js가 불필요합니다.
프로필과 프로젝트 구성
전역 정의는 프로필 config.yaml의 mcp.client.servers입니다. 프로젝트 파일은 표준 워크스페이스의 .anyy/mcp.json(현재 <ProfileHome>/workspace/.anyy/mcp.json)입니다. 대화 전환이나 세션 작업 디렉터리 변경으로 다른 파일이 선택되지 않습니다.
프로젝트는 mcpServers 객체를 씁니다.
{
"mcpServers": {
"context": {"enabled": false, "exposure": "deferred"},
"project-docs": {"url": "https://mcp.example.com", "exposure": "codemode"}
}
}
전체 프로젝트 정의는 같은 이름 프로필 정의를 대체합니다. command, url, type 없는 항목은 부분 재정의입니다. 같은 이름 프로필 서버가 필요하고 enabled, exposure, toolExposure만 가능합니다. 제공값은 상속값을 교체하며 toolExposure는 전체 순서 규칙 객체를 교체합니다. 인증 등 나머지는 프로필에서 옵니다. 전체 프로젝트 정의에는 공급자 auth 참조를 설정할 수 없습니다.
anyy mcp show SERVER_ID로 선택 출처와 재정의를 보세요. 잘못된 프로젝트 구성은 다른 정의로 조용히 바뀌지 않고 구성 진단에 나타납니다.
프로젝트 정의 추가와 제거
anyy mcp add project-docs --local --url https://mcp.example.com
anyy mcp remove project-docs --local
--local(또는 -l)은 이 프로필 프로젝트 파일만 기록합니다. 추가는 --force 없이 같은 이름 항목을 대체합니다. 제거는 그 항목만 삭제하고 프로필 정의·저장 권한을 보존하며 항목이 없으면 오류입니다. 파일 편집은 실행 서버를 재연결하지 않습니다. 시작 또는 유휴 session.reload가 로드합니다. 같은 이름 재정의 제거 후 프로필 정의가 드러납니다. --local 없이는 일반 프로필 동작입니다.
값과 경로
일반 add/configure/set과 Dashboard 저장은 민감해 보이는 환경·헤더 이름, OAuth client secret도 입력 문자열 그대로 유지합니다. 자동 비밀 참조로 바꾸지 않습니다. 기존 Anyy 관리 비밀이 필요하면 명시 secret:를 쓰세요. 일반 문자열은 아래 표현식을 따릅니다.
stdio 환경 값, HTTP 헤더, OAuth clientSecret만 값 표현식을 씁니다. $VAR, ${VAR}는 Anyy 환경을 읽고 $$는 리터럴 $, $!는 리터럴 !입니다. !로 시작하면 로컬 셸을 실행해 공백 제거 출력을 씁니다. 평가는 한 번이며 확장값을 다시 평가하지 않습니다. 명령은 Anyy 프로세스 작업 디렉터리에서 10초·1 MiB 제한으로 실행됩니다.
프로필 정의에서 정확한 env:, secret:, file: 접두사는 기존 자격 증명 해석기를 먼저 쓰고 결과가 최종입니다. 전체 프로젝트 정의에서는 리터럴 텍스트입니다. 부분 재정의는 프로필 해석을 상속합니다. URL과 clientId, scope, callbackUrl 등 다른 OAuth 필드는 표현식을 쓰지 않습니다.
명령·인수 경로는 선행 ~를 확장합니다. cwd는 홈 상대·워크스페이스 상대도 지원합니다. $·! 표현식을 실행하지 않습니다. stdio 작업 디렉터리는 공개 워크스페이스 루트 및 !command 프로세스 디렉터리와 별개입니다.
로컬 서버 추가
anyy mcp add context \
--transport stdio \
--command npx \
--exposure codemode \
--args -y @upstash/context7-mcp
Anyy 옵션은 --args·-- 앞에 두며 나머지는 서버로 전달합니다. stdio용 선택 --cwd DIR은 저장 cwd와 같은 절대·워크스페이스 상대·선행 홈 경로를 받고 입력 공백을 자르지 않습니다. 필요하면 --env KEY=VALUE를 반복하며 민감 값에는 비밀 참조를 쓰세요. 로컬 서버는 Anyy 운영체제 접근으로 실행합니다.
원격 서버 추가
anyy mcp add remote-docs --url https://mcp.example.com
anyy mcp add provider-docs --url https://mcp.example.com --auth '{"provider":"provider-id"}'
anyy mcp add header-docs --url https://mcp.example.com --header Authorization=secret:mcp/header-docs/token
공급자 참조·Authorization 헤더가 없으면 자동 OAuth를 지원합니다. 익명 서버는 로그인 없이 연결할 수 있으며 초기 토큰 부재 자체가 재인증 필요는 아닙니다. auth는 공급자 JSON 객체, oauth는 별도 타입 옵션 객체입니다. 기존 등록은 예를 들어 --oauth '{"clientId":"registered-client"}'를 전달하세요. 이전 문자열 oauth, header, none 선택기는 거부합니다.
로그인 전에 저장하세요.
anyy mcp login remote-docs
서버가 저장 OAuth 클라이언트 자격 증명을 거부하면 거부된 로컬 인증 상태를 지우고 한 번 복구할 수 있으며 재로그인을 요청할 수 있습니다. 도구 호출을 재전송하지 않습니다. 코드 교환 검증자가 없으면 로그인 시도를 종료합니다.
브라우저 콜백과 수동 리디렉션
anyy mcp login remote-docs --timeout 300, Dashboard 저장 서버의 Sign in, TUI 설정의 Tools & MCP를 사용하세요. 브라우저에서 인증을 마칩니다. Anyy 호스트에 접근 못 하면 주소 표시줄의 전체 리디렉션 URL을 해당 로그인 입력에 붙여 넣습니다. URL은 비공개로 유지하세요.
CLI 기본 300초 제한은 인증만 포함하며 연결 검사·로그인 후 재연결은 제외합니다. 먼저 연결을 검사해 준비되었으면 Already signed in을 보고하며 일반 연결 오류로 로그인을 시작하지 않습니다. 명시 CLI 로그인은 비활성 저장 서버도 도구 활성화 없이 인증할 수 있습니다. 비대화형 터미널은 브라우저 콜백만 기다리고 붙여 넣기 URL을 읽지 않습니다.
TUI Ctrl+Y는 전체 인증 링크 복사, Esc는 취소입니다. Dashboard 로그인을 닫거나 페이지를 떠나면 대기 로그인이 취소됩니다. 완료하면 임시 링크·입력을 지웁니다.
도구 호출에 대화형 OAuth 권한이나 추가 범위가 필요하면 연결이 로그인 필요를 보고합니다. CLI·Dashboard·TUI에서 명시적으로 시작하세요. 실패 호출은 자동 갱신·재전송하지 않습니다. 취소는 전용 로그인 취소 결과로 끝내며 백그라운드 인증을 계속하지 않습니다.
다른 프로세스에서 로그인
같은 프로필/서버의 다른 로그인 프로세스가 자격 증명을 저장하면 인증 대기 연결은 모델 턴 시작에 확인합니다. 이미 준비한 요청은 원래 선언을 유지하고 새 도구는 후속 준비에 나타납니다. 백그라운드 자격 증명 폴링은 없습니다. 수동 구성은 여전히 시작·유휴 세션 리소스 다시 로드가 필요합니다. 이 감지 경로는 자격 증명 변경으로 일반 실패·닫힌 연결을 재시작하지 않습니다.
로그아웃
anyy mcp logout remote-docs
정확한 구성 Server ID를 쓰세요. 현재 로컬 자격 증명 항목을 제거하고 연결을 닫으며 구성·캐시 도구/리소스/지침은 유지합니다. 저장 항목이 없어도 성공 no-op입니다. 원격 토큰을 폐기하지 않으며 인식된 이전 대체 항목에는 추가 로그아웃이 필요할 수 있습니다. 가능하면 상주 프로필을 사용하고 제한 시간·실패 응답을 오프라인 파일 변경 허가로 보지 않습니다.
MCP는 주기적으로 도구 카탈로그를 폴링하지 않습니다. 연결, 명시 작업, 실제 목록 변경 알림에서 검색·갱신하며 알림 연결과 지원 세션 복구는 유지됩니다.
서버별 connect_timeout_ms는 폐기되었으니 제거하세요. call_timeout_ms는 초기화·검색·도구 요청에 각각 적용되며 열기 전체의 추가 기한은 없습니다. 적격 초기 HTTP 실패는 최종 오류 전 두 번 재시도할 수 있습니다.
HTTP 스트림과 토큰 갱신
초기화 후 기본 HTTP는 서버 요청·알림용 별도 GET 스트림을 엽니다. 공급자 인증은 GET을 포함한 실제 HTTP 발송마다 현재 토큰을 얻으며 MCP용 추가 사본을 저장하지 않습니다. 이 동작은 Dashboard·프로필 스위치를 추가하지 않습니다.
루프백 서버에 localhost Origin을 추가하지 않고 구성 헤더를 보존합니다. 명시 Origin은 덮어쓰지 않습니다. 서버 자체 Origin 검증은 유지됩니다.
서버가 커서를 제공하면 끊긴 이벤트 스트림을 GET과 마지막 이벤트 ID로 이어가며 도구 호출을 다시 보내지 않습니다. 커서 없는 응답 스트림이 답변 전에 끝나면 요청은 실패합니다. 연결을 닫으면 복구를 중지합니다.
같은 자격 증명 사용 프로세스는 토큰 갱신을 조정하고 추가 갱신 전에 저장 토큰을 다시 읽습니다. 모든 충돌·임대 유실 복구를 보장하지는 않습니다.
초기화와 워크스페이스 루트
초기화 결과에는 문자열 protocolVersion, 객체 capabilities, 문자열 name·version의 serverInfo가 필수입니다. 선택 instructions는 문자열입니다. 무효 결과는 연결됨 표시 대신 연결을 닫습니다. 누락·빈·공백 미제거 지침은 구별하며 프롬프트 요약 소비자가 표시용 공백을 정리합니다.
roots/list 요청은 상주 워크스페이스 표준 디렉터리 하나를 파일 루트로 받습니다. MCP 관리자 생성 때 고정되며 대화·논리 워크스페이스 전환이 공유 연결을 바꾸지 않습니다.
로컬 stdio는 기본 해당 디렉터리입니다. cwd는 절대·그곳 기준 상대·선행 홈 문법을 쓰며 명령·인수 경로도 선행 홈을 지원합니다. cwd 공백을 보존합니다. 프로세스 cwd를 변경해도 공개 루트는 그대로입니다. 루트는 컨텍스트이며 파일 권한 경계가 아닙니다.
도구 노출과 검색
| 노출 | 용도 |
|---|---|
codemode | 기본값. Codemode 검색·호출 |
deferred | 도구 검색 |
direct | 모델에 직접 선언 |
hidden | 모델·Codemode 검색 불가 |
순서 있는 toolExposure는 서버 기본값을 재정의합니다. 정확한 이름 우선, 나머지는 첫 일치 와일드카드입니다. 검색 프롬프트 없이 구성합니다.
anyy mcp configure context --exposure deferred
anyy mcp set context description 'Documentation tools'
anyy mcp set context toolExposure '{"get-*":"deferred","*":"hidden"}'
활성·노출은 선택 정의 파일이나 기존 프로젝트 재정의에 저장됩니다. 노출 변경은 재연결 없이 선언을 갱신하며 활성 변경은 해당 서버에만 적용됩니다. 저장 뒤 연결 실패면 상태를 확인하세요. 설정은 남습니다.
프로젝트 재정의 없는 프로필 서버는 anyy mcp disable SERVER_ID --project·enable SERVER_ID --project로 활성 상태만 프로젝트에 저장할 수 있습니다. 전체 프로젝트 정의·이미 재정의된 서버에는 적용되지 않으며 일반 enable/disable이 선택 출처를 씁니다.
configure --description, --tool-exposure, 일반 set/unset은 원시 프로필 정의를 편집합니다. configure --exposure·--enable과 합치지 말고 별도 실행하세요. 프로젝트 toolExposure는 숨겨진 프로필 정의 대신 해당 항목을 편집합니다.
고정 Pi v1.2 MCP 구성과 등록을 따릅니다. RPC tool_exposure는 맵 경계에서 순서를 보존하는 JSON 문자열이며 저장 구성에는 단일 순서 toolExposure가 있습니다.
MCP 도구는 mcp-* 개인 모음을 생성·활성화하지 않습니다. 일반 모음·역할·상위 이름 제한은 별도입니다. 전역 mcp.client.enabled, tools.include, tools.exclude, tools.trusted, --include, --exclude, --activate-toolset, 이전 선택 프롬프트는 폐기되었습니다. 무시하지 않고 거부하므로 제거하세요.
프롬프트의 서버 요약
실행 시작에 mcp_servers 섹션을 더합니다. Codemode·지연 검색 구성 활성 서버는 연결 중이어도 나옵니다. 직접 전용·숨김 전용·비활성은 제외하며 혼합 서버가 두 검색 경로를 쓰면 Codemode 라벨입니다. 목록은 발견 힌트이며 연결 성공 영수증이 아닙니다.
구성 설명이 우선하고 아니면 사용 가능 서버 지침 첫 줄을 씁니다. 이름 정렬, 요약 축소, 제한 목록의 생략 수를 적용합니다. 설명은 간결하게 쓰고 자격 증명을 넣지 마세요.
실행의 후속 도구 턴에는 고정됩니다. 설명·구성·새 지침은 다음 프롬프트에 나타나며 적격 서버가 없으면 섹션을 제거합니다.
도구 확인과 호출
anyy mcp show context
anyy mcp probe context
anyy mcp test context
anyy mcp list
anyy mcp status --json
anyy mcp logs context
anyy mcp reload context
# If the inspected server advertises a search tool with a query field:
anyy mcp call docs.search --args '{"query":"Anyy"}'
예시 호출입니다. show/probe의 원래 서버 도구 이름·정확한 인수를 쓰세요. 모델 이름은 네임스페이스와 정리·충돌 접미사가 있을 수 있으며 Codemode 검색은 JavaScript 식별자를 반환합니다. 이름을 조합하지 말고 실시간 선언을 쓰세요. Codemode 검색과 도구 검색을 참조하세요.
anyy mcp reload는 로드 구성으로 재연결하고 편집 파일을 다시 읽지 않습니다. 시작과 유휴 session.reload가 프로필·프로젝트 파일을 읽습니다. 별도 감시기는 없습니다. 변경 적용을 참조하세요.
점검은 선택이며 저장·활성화 게이트가 아닙니다. 단일 tools 인벤토리는 name, visible_name, description, exposure, offered 사실입니다. offered는 현재 서버 제공이며 승인 결과가 아닙니다. 준비 호출은 실행할 때 현재 서버·제공을 결정합니다.
새 직접 호출은 현재 JSON Schema로 검증합니다. 교체 전에 준비된 호출은 선언 스키마·검증 인수를 유지하고 실행 시 현재 서버를 찾습니다. 교체는 기존 진행 연결을 닫지만 새 서버에 재전송하지 않습니다. 선택 모델 도구와 anyy mcp call은 쓰기도 직접 실행합니다. 프로필 소유권, 서버 인증, 비밀 보호, 일반 이름 제한은 유지됩니다. 이전 승인/실행 정책 키는 계속 거부합니다.
리소스와 템플릿
공유 도구 세 개를 제공합니다.
| 도구 | 입력 | 프로그램 결과 |
|---|---|---|
list_mcp_resources | 선택 server, cursor | resources, 선택 server, nextCursor, errors |
list_mcp_resource_templates | 선택 server, cursor | resourceTemplates, 선택 server, nextCursor, errors |
read_mcp_resource | 필수 server, uri | {server, uri, contents} |
서버 지정은 한 페이지이며 다음에 nextCursor를 전달합니다. 생략하면 적격 서버의 모든 페이지를 수집합니다. 커서에는 서버가 필요합니다. 통합 목록은 성공 결과를 보존하고 실패를 errors에 담으며 선택 서버 실패는 호출을 reject합니다.
리소스 기능을 보고하고 숨김 아닌 노출의 활성 서버가 적격입니다. 가장 넓은 direct, codemode, deferred 순 노출을 씁니다. 기능 확인 후 나타나고 철회되면 이전 정의를 숨깁니다. 인벤토리는 시작 때가 아닌 호출 때 가져옵니다.
읽기는 완전 프로그램 JSON을 보존합니다. 모델은 텍스트·이미지·저장 파일 참조를 받고 긴 텍스트는 공유 20 KiB 제한입니다. MCP App UI 리소스는 목록에서 제외합니다. 전달 실패로 성공 읽기를 반복하지 않습니다.
이전 서버별 리소스/프롬프트 이름과 tools.resources/tools.prompts는 폐기되었습니다. false, null도 거부하므로 제거하세요. 상태는 resources_advertised, prompts_advertised, server_capabilities만 유지하고 이전 enabled/posture/count를 제거합니다. 원시 SDK 프롬프트 메서드는 생성 에이전트 도구가 아닌 프로토콜 API입니다.
다른 MCP 클라이언트를 Anyy에 연결
anyy mcp serve는 stdio로 상주 비서의 대화·메시지·이벤트를 노출합니다. 기본 도구는 conversations_list, conversation_get, messages_read, events_poll, events_wait, messages_send입니다.
mcp.server.scopes는 conversations, messaging만 지원합니다. 생략하면 둘 다, []면 도구 없음입니다. 승인 목록·응답 도구는 제거되었습니다. 이전 approvals, 미구현 자리표시 범위, expose_approvals/expose_tools를 거부합니다. 작업은 기존 Gateway RPC를 거칩니다.
대화 결과 API
messages_send는 session_id, text만 받습니다.
{"session_id":"ses_example","text":"Summarize my tasks"}
session.submit으로 수용한 뒤 원래 submission_id로 execution.await를 호출합니다. 결과 JSON 텍스트 내용:
| 필드 | 의미 |
|---|---|
submission | submission_id 포함 원래 수용 영수증 |
execution | 해당 입력 실제 호출의 관찰 상태·결과 |
messages | 해당 호출 기록 참조에서 로드한 순서 결과 메시지 |
timed_out | 결과 전 관찰 만료 여부 |
같은 세션 후속 프롬프트가 대체할 수 없습니다. messages_read는 이력 조회이며 대체 답변 출처가 아닙니다. 일반 보호·첨부 처리는 적용됩니다.
성공 완료나 실제 확인 질문 중단에는 isError=false입니다. suspended는 확인 핸들을 유지하며 입력 필요이지 최종 답이 아닙니다. 실패, 중단, 지운 입력, 제한 시간, 비최종 상태는 isError=true입니다. 유휴 레인은 outcome=succeeded일 때만 성공입니다.
Gateway RPC 직접 클라이언트는 수용의 두 ID를 보존하세요.
{"execution_id":"exec_example","submission_id":"sub_example","timeout_ms":30000}
execution.await는 {execution, submission_id, timed_out, messages}를 반환합니다. 입력 선택 전 준비 실패를 포함해 원래 예약·선택 실행과 복구 계보를 따릅니다. 미선택 입력을 지우면 outcome=interrupted, stop_reason=input_cleared, 결과 메시지 없음입니다. 대기는 입력을 활성화하지 않습니다.
제한 시간은 timed_out=true와 빈 messages를 반환합니다. 제한 시간·호출자 취소는 관찰만 끝내며 수락 작업은 계속합니다. execution_id만으로는 재사용 레인을 관찰하며 특정 제출 결과를 식별하지 않습니다. 같은 요청을 다시 내기 전에 세션을 확인하세요.
비활성화와 제거
anyy mcp disable context
anyy mcp remove context
비활성화는 구성을 보존합니다. 일반 anyy mcp remove는 프로필 안의 해당 MCP 서버 정의와 Anyy 관리 자격 증명을 제거하며 프로필 자체를 삭제하지 않습니다. remove --local은 프로젝트 항목만 제거하며 권한은 보존합니다. 일반 개인 도구 모음은 유지됩니다. 프로필 내 MCP 서버 정의 작업의 --force는 스크립트 교체·제거 확인이며 프로필 소유권·자격 증명 처리를 우회하지 않습니다.
문제 해결
| 문제 | 확인 사항 |
|---|---|
| 로컬 서버 시작 불가 | 명령, 인수, 실행 파일, 환경 |
| 원격 권한 없음 | 공급자 참조, OAuth 상태, 보호 헤더 |
| 도구 사용 불가 | 서버 활성, 노출, 현재 제공 |
| 스키마 변경 | 현재 정의 확인 후 유효 인수로 재시도 |
| 파일 이전 내용 유지 | 유휴 세션 다시 로드·재시작으로 재읽고 선택 출처 확인 |
양식·확인은 Dashboard MCP를 참조하세요.
결과와 첨부
프로그램 결과는 structuredContent의 null, false, 숫자, 문자열, 배열 등 허용 프로토콜 값을 보존합니다. content 블록이 있으면 이를 모델 콘텐츠로 변환하고 structuredContent를 별도 추가하지 않습니다. content가 비고 structuredContent가 있으면 JSON을 모델 텍스트로 형식화합니다. 같은 비밀 보호·20 KiB 처리를 거칩니다. 출력 스키마는 선언 프로그램 반환에 영향을 줄 뿐 원격 결과의 로컬 검증 게이트가 아닙니다. 모델은 순서 텍스트·이미지를 보존합니다. 오디오·알 수 없는 블록은 Pi 텍스트 자리표시, 내장 리소스는 텍스트/이미지·저장 바이너리가 됩니다. 20 KiB 초과는 저장 전체 출력과 앞/뒤 투영을 씁니다.
resolve된 원격 isError는 계속 오류 결과입니다. 전송·JSON-RPC 예외는 reject합니다. 이미지·저장 파일 전달은 기존 세션 소유 아티팩트 경로로 순서를 유지하며 실패 때 원격 호출을 반복하지 않습니다. 텍스트는 저장 전에 보호합니다. 변환이 완료를 기다리기 전에 모든 블록 저장을 시작하므로 잘못된 블록이 변환을 거부해도 시작한 저장은 마칠 수 있습니다.
일반 네트워크 실패는 도구 호출을 자동 재전송하지 않습니다. 만료 세션 복구는 별도입니다. OAuth 등록·토큰 갱신·전송 요건은 외부 서비스에 따릅니다. 의존 전에 실제 연결과 도구 결과를 확인하세요.