Discord Agent Proxy 사용 문서

Discord Agent Proxy는 독립적으로 배포되는 서비스입니다. 자신의 Discord 계정 자격 증명을 보관하고 Discord와 상시 연결을 유지하며, 이 계정의 기능을 MCP와 REST API 두 인터페이스를 통해 공개하여 AI 또는 프로그램이 대신 Discord를 조작할 수 있도록 합니다. 컨테이너에는 어떠한 AI 모델도 포함되어 있지 않으며, 실행만 담당합니다. 호출은 AI 클라이언트(Claude, Cursor 등) 또는 자체 프로그램에서 시작합니다.

AI 클라이언트  ──MCP /mcp──┐
                           ├─→ Discord Agent Proxy ──→ Discord
자체 프로그램 ──REST /api───┘      （계정 자격 증명 보관）

⚠️ 사용 전 필독

프로그램으로 개인 계정(self-bot)을 자동화하여 조작하는 것은 Discord 서비스 약관을 위반하며, 계정이 차단될 위험이 있습니다. 이는 이 서비스의 고유한 전제입니다. 자신의 계정 자격 증명을 제공하고 위험은 스스로 부담합니다. 전용 부계정을 사용하고, 주 계정은 사용하지 않는 것을 강력히 권장합니다.

서비스 배포

콘솔 → 애플리케이션에 들어가 Discord Agent Proxy를 찾아 애플리케이션을 생성합니다. 생성 후 먼저 구독을 활성화한 다음, 설정 페이지에 Discord 계정 자격 증명을 입력하고 배포합니다. 인스턴스 리소스는 플랫폼에서 자동으로 구성하므로 사양을 선택할 필요가 없습니다. 배포를 제출하면 애플리케이션 관리 페이지로 이동하며, Telegram, WeChat 배포와 동일한 「개요 / 로그 / 문서」 레이아웃을 사용합니다. 「개요」에는 인스턴스와 구독 상태가 표시되며, 계정 조회를 통해 Discord가 연결되었는지 확인합니다. 컨테이너가 정상적으로 실행 중이라고 해서 계정이 반드시 연결된 것은 아닙니다. 「개요」의 Discord 계정 카드에서는 두 가지 연결 정보를 제공합니다.

항목	예시	용도
MCP 연결 주소	`https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/mcp`	AI 클라이언트에 구성
액세스 토큰	`V0p7kAWY...`	인증용, 아래 참조

콘솔에서 인터페이스 조회 및 테스트

해당 애플리케이션의 「문서」 탭을 열면, 전체 14개 REST 작업의 요청 매개변수, 응답 구조와 Shell, Python, JavaScript 등의 언어 예시를 확인할 수 있습니다. 인스턴스 주소와 액세스 토큰은 자동으로 입력되며, 토큰은 기본적으로 숨겨집니다. GET /api/whoami를 선택하고 「테스트」를 클릭하면 프록시가 연결한 계정을 확인할 수 있습니다. 메시지 전송, 편집 또는 삭제 등의 작업은 실제 Discord 계정에 적용되므로, 테스트 전에 요청 내용을 확인하십시오. 「OpenAPI (JSON) 다운로드」를 통해 전체 인터페이스 정의를 내보낼 수 있습니다. 파일에는 인스턴스 주소가 포함되지만 액세스 토큰은 포함되지 않습니다. Discord 계정 자격 증명을 변경해야 하는 경우, 「개요」에서 「재배포」를 선택하고 새 자격 증명을 입력한 후 제출하면 됩니다.

Discord 계정 자격 증명 가져오는 방법

컴퓨터 브라우저에서 Discord에 로그인합니다(discord.com/app)
F12를 눌러 개발자 도구를 열고 Network(네트워크) 패널로 전환합니다
Discord에서 아무 채널이나 클릭하고 요청 목록을 관찰합니다
discord.com/api로 전송된 임의의 요청을 열고, **Request Headers(요청 헤더)**에서 authorization 필드를 찾습니다
해당 값을 복사합니다

이 자격 증명 문자열은 계정 로그인 상태와 동일하므로, 절대로 누구와도 공유하지 마십시오. 유출된 경우 Discord에서 비밀번호를 변경하면 즉시 무효화할 수 있습니다.

인증 방식

/health와 /readyz를 제외한 모든 인터페이스는 요청 헤더에 액세스 토큰을 포함해야 합니다.

Authorization: Bearer <액세스 토큰>

주의: 이 서비스는 요청 헤더 인증만 허용하며, ?token=xxx처럼 URL 뒤에 토큰을 붙이는 방식은 지원하지 않습니다. 브라우저에서 직접 인터페이스 주소를 열면 401 unauthorized가 반환되며, 이는 정상 현상으로 배포 실패를 의미하지 않습니다. 프로세스가 살아 있는지 확인하려면 /health에 접속하십시오. Discord 연결이 요청을 처리할 수 있는지 확인하려면 /readyz에 접속하십시오. 이 두 프로브는 모두 인증이 필요 없습니다. 프록시 액세스 토큰이 구성되지 않은 경우, 보호된 인터페이스는 익명으로 공개되지 않고 503을 반환합니다.

서비스 상태 확인

curl https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/health
curl https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/readyz

/health는 HTTP 프로세스가 살아 있음을 나타낼 뿐입니다.

{ "status": "ok" }

/readyz는 Discord Gateway를 사용할 수 있는지를 나타냅니다. 연결이 정상일 때 HTTP 200을 반환합니다.

{ "status": "ready", "gateway_ready": true }

연결 중이거나, 자격 증명이 유효하지 않거나, 연결이 끊어진 경우 Kubernetes의 Pod 직접 프로브는 HTTP 503을 반환하며, 인스턴스 백엔드에서 자동으로 재시도합니다. 이때 Pod는 일시적으로 공개 Service에서 제외되므로 인스턴스 도메인을 통해 이 진단 JSON을 읽을 수 있다고 보장할 수 없습니다. 콘솔에서 Deployment 상태를 확인하고 Ready로 복구된 후 MCP / REST를 호출하십시오.

AI 클라이언트에서 사용하기(MCP)

Claude Code를 예로 들면 다음과 같습니다.

claude mcp add --transport http discord \
  https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/mcp \
  --header "Authorization: Bearer <액세스 토큰>"

Cursor 등 정적 요청 헤더를 지원하는 클라이언트는 해당 최신 문서에 따라 Streamable HTTP 주소를 구성하십시오. 다음 구조를 허용하는 클라이언트는 사용할 수 있습니다.

{
  "mcpServers": {
    "discord": {
      "type": "http",
      "url": "https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer <액세스 토큰>"
      }
    }
  }
}

이는 모든 MCP 클라이언트에 공통으로 적용되는 구성 형식이 아닙니다. Claude Desktop / Claude.ai의 원격 커넥터는 클라우드에서 연결을 수립하며, 로컬 claude_desktop_config.json에 있는 어떠한 HTTP 요청 헤더도 읽지 않습니다. 현재 정적 Bearer 요청 헤더가 필요한 경우 Claude Code 또는 해당 기능을 명시적으로 지원하는 클라이언트를 사용하십시오. 구성이 완료되면 자연어로 AI에게 Discord 조작을 직접 지시할 수 있습니다. 예를 들면 다음과 같습니다.

「프로젝트 토론」 채널에 새 메시지가 있는지 확인하고, 누군가 출시 일정을 물었다면 이번 주 금요일이라고 답장해 줘.

사용 가능한 도구

MCP 도구	역할
`discord_whoami`	현재 에이전트가 어떤 계정인지 확인
`discord_list_guilds`	계정이 가입한 모든 서버 나열
`discord_list_channels`	특정 서버 아래의 채널 나열
`discord_create_text_channel`	텍스트 채널 생성
`discord_list_members`	서버 멤버 나열
`discord_send_message`	메시지 전송(특정 메시지에 답장 지정 가능)
`discord_read_messages`	채널의 최근 메시지 읽기
`discord_edit_message`	자신이 보낸 메시지 편집
`discord_delete_message`	메시지 삭제
`discord_search_messages`	채널 내에서 메시지 검색
`discord_add_reaction`	메시지에 이모지 반응 추가
`discord_pin_message`	메시지 고정
`discord_create_dm`	일대일 개인 메시지 시작, 채널 ID 반환
`discord_send_dm`	특정 사용자에게 개인 메시지 보내기

프로그램에서 사용(REST API)

모든 REST 인터페이스는 /api 아래에 마운트되며, 응답 본문은 통일하여 {"data": ...}이고, 오류 시에는 {"error": "..."}입니다.

현재 계정 확인

curl https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/api/whoami \
  -H "Authorization: Bearer <你的访问令牌>"

메시지 전송

curl -X POST https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/api/messages \
  -H "Authorization: Bearer <你的访问令牌>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <本次发送的唯一操作 ID>" \
  -d '{"channel_id": "1234567890", "content": "你好"}'

같은 전송을 재시도할 때는 동일한 Idempotency-Key를 재사용하면 프로세스가 최초 결과를 반환하고 중복 전송하지 않습니다. 인스턴스 재시작 시 최대 5,000건의 메모리 중복 제거 기록이 지워지므로, 호출자는 여전히 장기 전송 상태를 직접 추적해야 합니다. 선택적 매개변수 reply_to는 지정한 메시지에 답장하는 데 사용됩니다:

{ "channel_id": "1234567890", "content": "收到", "reply_to": "9876543210" }

메시지 읽기

curl "https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/api/channels/1234567890/messages?limit=20" \
  -H "Authorization: Bearer <你的访问令牌>"

전체 인터페이스 목록

메서드 및 경로	매개변수	역할
`GET /api/whoami`	—	현재 에이전트의 계정 정보
`GET /api/guilds`	—	계정이 가입한 서버 목록
`GET /api/guilds/{guild_id}/channels`	—	서버 아래의 채널 목록
`POST /api/guilds/{guild_id}/channels`	`{name}`	텍스트 채널 생성
`GET /api/guilds/{guild_id}/members`	`?limit=`(기본값 100)	서버 멤버 목록
`POST /api/messages`	`{channel_id, content, reply_to?}`	메시지 전송
`GET /api/channels/{channel_id}/messages`	`?limit=`(기본값 50, 최대 100)	최근 메시지 읽기
`GET /api/channels/{channel_id}/messages/search`	`?q=`(필수)`&limit=`(기본값 25)	메시지 검색
`PATCH /api/channels/{channel_id}/messages/{message_id}`	`{content}`	메시지 편집
`DELETE /api/channels/{channel_id}/messages/{message_id}`	—	메시지 삭제
`POST /api/channels/{channel_id}/messages/{message_id}/reactions`	`{emoji}`	이모지 반응 추가
`POST /api/channels/{channel_id}/messages/{message_id}/pin`	—	메시지 고정
`POST /api/dms`	`{recipient_id}`	개인 메시지 시작, 채널 ID 반환
`POST /api/dms/send`	`{recipient_id, content}`	개인 메시지 전송

채널 ID와 사용자 ID를 얻는 방법

Discord 클라이언트에서 차례로 사용자 설정 → 고급 설정을 열고 개발자 모드를 활성화합니다. 이후 임의의 채널이나 사용자를 마우스 오른쪽 버튼으로 클릭하면 메뉴에 「ID 복사」가 표시됩니다. 직접 GET /api/guilds 및 GET /api/guilds/{guild_id}/channels를 호출하여 열거할 수도 있습니다.

자주 묻는 질문

401 unauthorized 반환 액세스 토큰이 올바르지 않거나 ?token= 방식으로 전달했습니다. 토큰이 요청 헤더 Authorization: Bearer <토큰>을 통해 전달되며 콘솔에 표시된 것과 일치하는지 확인하세요. 503 반환 Discord와의 연결이 아직 수립되지 않았습니다. 먼저 /readyz에 접근하여 gateway_ready를 확인하세요. 장시간 false이면 대부분 계정 자격 증명이 만료된 것이므로 다시 가져와 재배포하세요. 403 또는 404 반환 계정 자체에 해당 권한이 없거나(예: 해당 서버에 없거나, 해당 채널에서 발언할 권한이 없음) ID를 잘못 입력한 것입니다. 이러한 오류는 Discord에서 발생한 것이며, 프록시 서비스의 문제가 아닙니다. 429 반환 Discord의 빈도 제한이 발동되었습니다. 응답의 retry_after 필드는 권장 대기 시간을 초 단위로 제공합니다. 호출 빈도를 낮추세요. 메시지 전송 후 계정이 차단됨 앞서 언급했듯이 개인 계정의 자동화 작업은 Discord 서비스 약관을 위반합니다. 전용 부계정을 사용하고, 작업 빈도를 제어하며, 대량 발송 등의 민감한 행동을 피하세요.

검증 범위

2026년 8월 1일의 프로덕션 smoke는 전용 계정을 사용하여 계정, 서버, 채널, 멤버, 메시지 읽기, 검색, 전송, 편집, 반응 및 삭제를 검증했습니다. 자동화 테스트는 인증, 매개변수 검증, 오류 매핑 및 현재 종속 라이브러리 서명을 포괄합니다. worker 또는 chart 변경 후에는 여전히 smoke를 다시 실행해야 하며, 과거 검증을 지속적인 가용성의 증명으로 간주해서는 안 됩니다.

시작하기

AI 채팅

AI 이미지

AI 비디오

AI 오디오

웹 & 데이터

CAPTCHA

신원

Coding

추가 가이드

Discord Agent Proxy 사용 문서

⚠️ 사용 전 필독

서비스 배포

콘솔에서 인터페이스 조회 및 테스트

Discord 계정 자격 증명 가져오는 방법

인증 방식

서비스 상태 확인

AI 클라이언트에서 사용하기(MCP)

사용 가능한 도구

프로그램에서 사용(REST API)

현재 계정 확인

메시지 전송

메시지 읽기

전체 인터페이스 목록

채널 ID와 사용자 ID를 얻는 방법

자주 묻는 질문

검증 범위

​⚠️ 사용 전 필독

​서비스 배포

​콘솔에서 인터페이스 조회 및 테스트

​Discord 계정 자격 증명 가져오는 방법

​인증 방식

​서비스 상태 확인

​AI 클라이언트에서 사용하기(MCP)

​사용 가능한 도구

​프로그램에서 사용(REST API)

​현재 계정 확인

​메시지 전송

​메시지 읽기

​전체 인터페이스 목록

​채널 ID와 사용자 ID를 얻는 방법

​자주 묻는 질문

​검증 범위

⚠️ 사용 전 필독

서비스 배포

콘솔에서 인터페이스 조회 및 테스트

Discord 계정 자격 증명 가져오는 방법

인증 방식

서비스 상태 확인

AI 클라이언트에서 사용하기(MCP)

사용 가능한 도구

프로그램에서 사용(REST API)

현재 계정 확인

메시지 전송

메시지 읽기

전체 인터페이스 목록

채널 ID와 사용자 ID를 얻는 방법

자주 묻는 질문

검증 범위