Claude와 Cursor를 연결해 MCP로 AgencyHandy 사용하기

AgencyHandy MCP 연결을 사용하면 Claude 또는 Cursor에 자연어로 말해 AgencyHandy 워크스페이스의 일상 업무를 실행할 수 있습니다 — 화면을 일일이 열 필요가 없습니다. 통제권은 항상 당신에게 있습니다. Claude와 Cursor는 생성한 워크스페이스 API 키로만 동작하며, 이름이 여러 사람과 일치하면 확인을 요청합니다.

연결하는 두 가지 방법

에이전트 실행 위치	연결 방법	설정
내 컴퓨터 — Claude Desktop 또는 Cursor	앱이 실행하는 `agencyhandy-mcp` 패키지	아래 Claude 또는 Cursor MCP 설정 — Node.js 20+ 필요
클라우드 — Cloudflare Workers, Vercel, n8n, 호스팅형 Claude 또는 Cursor	`https://mcp.agencyhandy.com/` 의 호스팅형 MCP 서버	아래 클라우드 에이전트 연결 — 설치 불필요

두 방법 모두 같은 워크스페이스 API 키를 사용하며 에이전트에 동일한 도구를 제공합니다.

Workspace Config 를 열고 API keys 를 관리할 수 있는 역할(보통 SuperAdmin 또는 Admin)이 필요합니다. 로컬 설정에서는 Claude Desktop 또는 Cursor가 실행되는 컴퓨터에 Node.js 20+ 도 필요합니다. 호스팅형 서버는 설치가 전혀 필요 없습니다.

요구 사항

요구 사항	세부 정보
AgencyHandy 워크스페이스	Workspace Config → API Key 접근 권한
MCP 호스트	컴퓨터의 Claude Desktop 또는 Cursor, 혹은 HTTP로 MCP 서버를 호출할 수 있는 모든 에이전트
Node.js (로컬 설정 전용)	버전 20 이상 (`node -v` 로 확인)
MCP 패키지 (로컬 설정 전용)	`npx -y agencyhandy-mcp@1` (`1` 태그로 1.7.2+ 제공)

npm의 MCP 패키지는 agencyhandy-mcp입니다. Claude와 Cursor는 npx -y agencyhandy-mcp@1로 실행합니다.

Claude 또는 Cursor MCP 설정

Claude Desktop 또는 Cursor를 내 컴퓨터에서 실행할 때 사용하세요. 에이전트가 클라우드에서 실행된다면 클라우드 에이전트 연결 로 건너뛰세요.

Workspace Config 열기

AgencyHandy에서 Workspace Config(회사 설정)를 연 다음 API Key 탭으로 이동합니다.

워크스페이스 API 키 생성

새 워크스페이스 API 키를 만들거나 저장해 둔 키를 사용하세요. 표시되면 바로 복사하세요 — 이후 전체 키를 다시 볼 수 없습니다.

MCP 구성 복사

같은 API Key 탭의 Claude / Cursor MCP 설정 패널에서 Copy MCP config를 클릭해 키와 백엔드 URL이 포함된 JSON을 복사합니다.

Cursor 또는 Claude Desktop에 붙여넣기

구성을 다음에 붙여넣으세요:

Cursor: 프로젝트 또는 사용자 .mcp.json
Claude Desktop: claude_desktop_config.json

생성된 npx -y agencyhandy-mcp@1 명령과 API 키를 그대로 유지하세요.

다시 시작하고 프롬프트 시도

Cursor 또는 Claude Desktop을 완전히 종료한 뒤 다시 엽니다. 그런 다음 워크스페이스 모닝 브리핑처럼 간단한 요청을 해보세요.

Claude 또는 Cursor가 MCP 서버를 찾지 못하면 Node.js 20+ 설치 여부와 구성 저장 후 앱 재시작을 확인하세요.

클라우드 에이전트 연결 (호스팅형 서버)

패키지를 설치할 수 없는 환경에서 에이전트를 실행한다면 — Cloudflare Workers, Vercel 함수, n8n, 호스팅형 Claude나 Cursor — 저희가 운영하는 MCP 서버를 가리키도록 설정하세요:

https://mcp.agencyhandy.com/

설치할 것도, 유지할 서버도 없습니다. 같은 워크스페이스 API 키를 베어러 토큰으로 사용해 모든 요청을 인증하세요. 워크스페이스는 키에서 읽으므로 사용자마다 자신의 키로 연결합니다. Cursor, Claude Code 및 사용자 지정 헤더를 보낼 수 있는 모든 호스트:

{
  "mcpServers": {
    "agency-handy": {
      "url": "https://mcp.agencyhandy.com/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Claude Desktop 은 사용자 지정 헤더를 보낼 수 없으므로 mcp-remote 로 연결합니다:

{
  "mcpServers": {
    "agency-handy": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.agencyhandy.com/",
        "--header", "Authorization:Bearer YOUR_API_KEY"
      ]
    }
  }
}

명령줄에서 실행하는 Claude Code:

claude mcp add agency-handy --transport http https://mcp.agencyhandy.com/ \
  --header "Authorization: Bearer YOUR_API_KEY"

주소는 루트 경로 입니다 — /mcp 가 아니라 https://mcp.agencyhandy.com/. 서버가 응답하는지 확인하려면 https://mcp.agencyhandy.com/health 를 열어 보세요.

대신 HTTP API로 직접 연동을 만들고 있나요? 요청에 User-Agent 헤더를 함께 보내세요. Cloudflare Workers의 fetch() 를 비롯한 일부 런타임은 기본적으로 이 헤더를 보내지 않으며, 헤더가 없는 요청은 API에 도달하기 전에 거부됩니다.

예시 프롬프트

자연어를 사용하세요. 작업을 배정할 때는 올바른 사람을 고르기 위해 전체 이름이나 이메일을 우선하세요.

목표	예시 프롬프트
모닝 브리핑	“모닝 브리핑 해줘: 열린 티켓, 미결제 인보이스, 고객 대기 중인 제안서.”
티켓 배정	“Acme 홈페이지 리디자인 티켓을 Jordan Lee(jordan@agency.com)에게 배정해.”
인보이스 발송	“인보이스 INV-1042를 이메일로 고객에게 보내.”
리드 생성	“Bright Studio의 Nora Patel(nora@brightstudio.com) 리드를 만들어.”
인보이스 결제 완료 표시	“인보이스 INV-1042를 paid로 표시해.”

이름이 같은 사람이 두 명일 때

팀원 중 Sara가 두 명이면 Claude가 누구를 말하는지 묻습니다. ID를 지어내지 않으며 조용히 추측하지도 않습니다. 이름이 겹칠 수 있으면 프롬프트에 항상 전체 이름 또는 이메일을 포함하세요.

지금 되는 것 vs 아직 안 되는 것

지금 가능	MCP에서 아직 불가
제안서·프로젝트·티켓·인보이스 브리핑 및 조회	MCP에서 client chat 답장
티켓 및 기타 팀 작업 배정	—
리드 생성	—
인보이스 발송 및 결제 완료 표시	—

MCP는 API 키로 워크스페이스를 읽고 작업(생성·배정·발송·업데이트)할 수 있습니다. 클라이언트 채팅 답장은 아직 MCP로 제공되지 않습니다 — 해당 대화는 AgencyHandy를 사용하세요.

시작하기

워크스페이스 설정

CRM

서비스 & 주문

제안서 & 인보이스

팀 & 작업

양식 & 파일

계정 & 결제

결제

통합

Claude와 Cursor를 연결해 MCP로 AgencyHandy 사용하기

연결하는 두 가지 방법

요구 사항

Claude 또는 Cursor MCP 설정

클라우드 에이전트 연결 (호스팅형 서버)

예시 프롬프트

이름이 같은 사람이 두 명일 때

지금 되는 것 vs 아직 안 되는 것

관련

​연결하는 두 가지 방법

​요구 사항

​Claude 또는 Cursor MCP 설정

​클라우드 에이전트 연결 (호스팅형 서버)

​예시 프롬프트

​이름이 같은 사람이 두 명일 때

​지금 되는 것 vs 아직 안 되는 것

​관련

연결하는 두 가지 방법

요구 사항

Claude 또는 Cursor MCP 설정

클라우드 에이전트 연결 (호스팅형 서버)

예시 프롬프트

이름이 같은 사람이 두 명일 때

지금 되는 것 vs 아직 안 되는 것

관련