MCP4Acumatica

고지: 이 프로젝트는 독립적으로 만들어진 커뮤니티 연동이며 Acumatica, Inc.와 무관하고, Acumatica, Inc.의 보증이나 지원을 받지 않습니다. "Acumatica"는 Acumatica, Inc.의 등록 상표입니다. Acumatica 이름과 API의 사용은 상호운용성을 위한 목적으로만 제공됩니다.

원격 Model Context Protocol (MCP) 서버로, Claude를 Acumatica ERP 2025 R2에 연결합니다. Cloudflare Workers에서 실행되며 사용자의 Acumatica 인스턴스에 대해 사용자별 OAuth 인증을 처리합니다.

각 사용자는 자신의 Acumatica 자격 증명으로 인증합니다. 사용자의 Acumatica 역할이 접근할 수 있는 레코드를 제어합니다. MCP 서버는 접근을 위해 특정 Acumatica 역할이 있어야 하며, 동의 중간 화면을 표시하고, 데이터가 AI 모델에 도달하기 전에 민감한 필드를 자동으로 마스킹합니다.

기능

• 도구 49개 — 읽기 전용 조회 38개 + 유틸리티/검색 6개 + 스키마 지식 4개 + 쓰기 도구 1개(Customer 생성/수정, 기본 비활성화) (사용 가능한 도구 참조)

• 사용자별 OAuth — 각 사용자가 자신의 Acumatica 자격 증명(또는 SSO)으로 로그인합니다

• 역할 기반 접근 — Acumatica의 보안 모델이 각 사용자에게 보이는 내용을 제어합니다

• 접근 게이트 — 지정된 canary Generic Inquiry를 읽을 수 있는 사용자만 접속할 수 있습니다(제한 방식은 자유롭게 정하면 되며, MCP Access 같은 마커 역할이 권장됩니다)

• 동의 중간 화면 — 사용자는 AI 도구에 접근하기 전에 AI 데이터 처리를 확인해야 합니다

• 민감 필드 마스킹 — SSN, 은행 계좌, 급여 및 기타 PII 필드는 데이터가 서버에서 나가기 전에 자동으로 마스킹됩니다

• 요청 속도 제한 — 사용자당 기본적으로 동시 요청 3개, 분당 요청 40개이며, 두 값 모두 관리자 콘솔에서 조정할 수 있습니다. 모든 슬롯이 사용 중이면 요청이 곧바로 실패하는 대신 잠시 대기한 후 하나의 슬롯을 사용합니다. 거부되는 경우 { error: "rate_limited", retryAfterSeconds, actionRequired } 형태의 구조화된 응답으로 AI에게 재시도 루프를 돌지 않고 정확히 얼마나 기다려야 하는지 알려줍니다

• 페이지네이션 거부 — 목록/조회 도구는 결과가 레코드 상한에 도달하면 { truncated, paginationSupported: false, actionRequired } 형태의 구조화된 응답을 반환하고, AI가 도구를 다시 호출하는 대신 사용자에게 더 좁은 조건을 요청하도록 안내합니다

• 구조화된 감사 로깅 — 모든 도구 호출, 인증 이벤트, 필드 마스킹이 로그에 기록됩니다

• 관리자 콘솔 — /docs/admin에서 웹 기반 관리 인터페이스를 제공하며, 재배포 없이 로그를 확인하고 런타임 설정을 관리할 수 있습니다

• 장기 로그 보존 — Cloudflare Logpush를 통한 R2 기반 로그 저장소와 검색 가능한 로그 뷰어를 지원합니다

아키텍처

Claude (claude.ai / Desktop / API)
    |
    v  MCP over streamable-http
+----------------------------------+
|  Cloudflare Worker               |
|  OAuth 2.1 Provider              |
|    /authorize -> Acumatica login |
|    /callback  <- Acumatica       |
|    (access gate + OIDC userinfo) |
|    /consent   -> AI data consent |
|    /token, /register (DCR)       |
|    /mcp -> McpAgent DO (49 tools)|
+---------------+------------------+
                |  Bearer token (per-user)
                v
        Acumatica 25R2 SaaS
        Contract-Based REST API
        Default/25.200.001

사전 요구 사항

• Node.js >= 18

• Cloudflare 계정(Workers 유료 플랜 필요, Durable Objects 사용)

• Acumatica 2025 R2 인스턴스에 다음이 구성되어 있어야 합니다:

  • Connection Application이 Authorization Code OAuth 2.0 흐름으로 SM303010에 구성됨 (스코프는 서버가 요청 본문에 담아 보내며, 앱에 설정하지 않습니다)

  • 워커의 /callback 엔드포인트를 가리키는 redirect URI

  • MCPAccess Generic Inquiry (SM208000) — Expose via OData 가 활성화된 아주 간단한 canary GI이며, 로그인 접근 게이트가 사용자가 이 GI를 읽을 수 있는지 확인합니다. (자세한 내용은 아키텍처 문서 참조) GI 이름은 ACUMATICA_CANARY_GI로 변경할 수 있습니다

  • 해당 GI를 읽을 사용자를 제한하는 방법 — 권장 방식은 허용 사용자에게만 할당하는 MCP Access 역할(SM201005)입니다

설정

설치 경로는 세 가지입니다. 세 경로 모두 동일한 Acumatica측 사전 요구 사항을 필요로 하므로, 어떤 경로를 선택하든 그 사전 요구 사항을 먼저 완료하세요(아래 "Acumatica측 구성" 참조).

경로 A — Deploy to Cloudflare 버튼 (터미널 불필요)

이 버튼을 클릭하면 저장소가 GitHub 계정으로 포크되고 wrangler.jsonc를 읽어 KV 네임스페이스와 R2 버킷을 자동 생성하고 암호 변수를 물어본 뒤 배포합니다. 단계별로 살펴봅니다:

1. 버튼을 클릭하세요. Cloudflare가 로그인(또는 계정 생성)과 GitHub 포크 승인을 요청합니다.

2. 바인딩을 확인하세요. KV 네임스페이스를 두 번 생성하라는 메시지가 나타납니다. 한 번은 TOKEN_STORE 바인딩용(앱 데이터: 토큰, OAuth 상태, 캐시, 구성, 관리자 세션)이고, 또 한 번은 OAUTH_KV용(OAuth 라이브러리가 내부적으로 사용)입니다. 이는 정상적인 동작이며, 둘은 서로 다른 바인딩으로 키를 공유하지 않습니다.

   ⚠️ 두 네임스페이스는 다른 이름을 지정하세요 (예: TOKEN_STORE에는 mcp4acumatica-app, OAUTH_KV에는 mcp4acumatica-oauth). Cloudflare 자동 프로비저닝은 Worker 이름에서 기본 제목(title)을 생성하기 때문에 두 필드의 기본값이 모두 mcp4acumatica로 지정됩니다 — 그래서 같은 제목의 네임스페이스가 두 개 만들어지면 "Cannot provision a KV Namespace with the title … because it already exists." 오류가 발생합니다. 이미 오류가 발생했다면 절반만 완료된 네임스페이스가 남아 있습니다. Storage & Databases → KV로 이동하여 만들어졌다가 버려진 mcp4acumatica 네임스페이스를 삭제하고, 서로 다른 이름을 사용해 다시 시도하세요. (Cloudflare GUI 자동 프로비저닝은 두 바인딩을 하나의 네임스페이스에 연결할 수 없을 뿐 아니라, 설정에서 서로 다른 제목을 넣어 둘 수도 없습니다. 따라서 서로 이름이 다른 네임스페이스 두 개를 만드는 것이 올바른 방법입니다. GUI가 계속 실패한다면 아래 터미널 설치 경로를 이용하세요. setup.sh는 네임스페이스를 하나만 만든 뒤 두 바인딩을 모두 연결해 줍니다.)

3. Secrets를 설정하세요. 메시지가 표시되면 값을 붙여넣습니다:

   • ACUMATICA_CLIENT_ID — Connected Application(SM303010)에서 가져온 값

   • ACUMATICA_CLIENT_SECRET — 같은 화면에서 가져온 비밀 키

   • COOKIE_ENCRYPTION_KEY — 아무 웹 페이지를 브라우저 콘솔에서 열고 다음을 실행하세요:

     [...crypto.getRandomValues(new Uint8Array(32))].map(b => b.toString(16).padStart(2,'0')).join('')

     그 결과 나오는 64자리 hexadecimal 문자열을 사용하세요.

   • ADMIN_SECRET — 직접 기억할 수 있는 암호( /docs/admin 콘솔을 보호하는 값). 특별히 원하는 값이 없으면 [...crypto.getRandomValues(new Uint8Array(24))].map(b => b.toString(16).padStart(2,'0')).join('') 를 실행해서 생성하세요.

4. 배포하세요. Cloudflare가 포크를 Workers Builds에 연결하고 첫 배포를 진행합니다.

5. Acumatica 변수를 업데이트하세요. 배포가 완료되어 있으면 Cloudflare 대시보드에서 Workers & Pages → mcp4acumatica → Settings → Variables and Secrets를 열고 다음 값을 수정합니다:

   • ACUMATICA_URL (예: https://yourcompany.acumatica.com)

   • ACUMATICA_TENANT (로그인 회사)

   • 필요한 경우 ACUMATICA_MAX_RECORDS, ACUMATICA_CANARY_GI, REDACT_PATTERNS, REDACT_SKIP Save and Deploy를 클릭하면 Cloudflare가 새 값으로 재배포합니다.

6. Connected Application에 redirect URI를 추가하세요. 이제 워커가 https://mcp4acumatica.<your-account>.workers.dev 주소로 접근됩니다. Acumatica의 SM303010 화면에 있는 redirect URI 목록에 https://<that-host>/callback을 추가하세요. (사용자 지정 도메인을 사용하려면 아래 "사용자 지정 도메인" 참조)

7. 배포를 테스트하세요. https://<your-host>/docs/admin/preflight로 접속해 ADMIN_SECRET으로 로그인한 뒤 사전 점검 진단을 실행합니다. Acumatica 연결, OIDC discovery endpoint, Connected App 자격 증명, 테넌트 경로, Contract API 버전을 검사합니다. 잘못된 구성이 있다면 이름을 지정하며 알려줍니다.

이제 Claude가 접속할 수 있습니다(아래 "Claude 연결" 참조).

경로 B — 원라이너 설치 스크립트 (터미널)

git, node, npm이 이미 있다면 다음 명령을 실행합니다:

curl -fsSL https://mcp4acumatica.hallboys.com/install.sh | bash

이 명령은 리포지토리를 클로한 뒤 dependencies를 설치하고 ./setup.sh를 실행합니다. 설정 스크립트는 필요한 Acumen 정보(URL, 테넌트, Connected App client ID와 secret)를 입력받고, 암호 값과 트리 키를 자동 생성하고, KV 네임스페이스와 R2 버킷을 만들고, secrets를 업로드하고, 배포한 뒤 사전 검사를 실행합니다.

아래를 통해 스크립트의 내용을 먼저 확인할 수 있습니다:

curl -fsSL https://mcp4acumatica.hallboys.com/install.sh -o install.sh
less install.sh   # read it
bash install.sh   # then run

경로 C — 수동 수동 설정 (터미널)

1. 클론 및 설치

git clone https://github.com/hallboys/MCP4Acumatica.git
cd MCP4Acumatica
npm install

2. KV 네임스페이스 생성

npx wrangler kv namespace create TOKEN_STORE

입력한 결과 네임스페이스 ID를 기억해 두세요. 다음 단계에서 wrangler.jsonc에 붙여넣게 됩니다. 같은 ID가 TOKEN_STORE와 OAUTH_KV 바인딩에 모두 사용됩니다.

3. wrangler 설정

wrangler.jsonc는 저장소에 배포 템플릿으로 유지됩니다. 내용을 그대로 수정하고 다음 값을 채웁니다:

• 2단계에서 얻은 KV 네임스페이스 ID (TOKEN_STORE와 OAUTH_KV 어느 바인딩에도 사용 — 동일한 ID)

• ACUMATICA_URL — Acumatica 인스턴스 URL (예: https://yourcompany.acumatica.com)

• ACUMATICA_TENANT — Acumatica 회사/테넌트 이름

로컬 값이 git status에 나타나지 않게 하여도(충돌 없이 업데이트를 받을 수 있도록), 다음 파일에 로컬 값 넣지 않으려면:

git update-index --skip-worktree wrangler.jsonc

4. Secrets 설정

npx wrangler secret put ACUMATICA_CLIENT_ID
npx wrangler secret put ACUMATICA_CLIENT_SECRET
npx wrangler secret put COOKIE_ENCRYPTION_KEY      # use `openssl rand -hex 32`
npx wrangler secret put ADMIN_SECRET                # any password — protects /docs/admin

5. 배포

npx wrangler deploy

6. 로컬 개발 (선택)

cp .dev.vars.example .dev.vars
# Edit .dev.vars with your Acumatica credentials
npx wrangler dev

Acumatica측 구성

이 단계는 어떤 설치 경로를 선택하든 반드시 필요합니다. Acumen의 API가 이러한 구성을 제어할 수 없으므로 자동화할 수 없습니다.

Connected Application (SM303010)

1. Acumen에서 System > Integration > Connected Application (SM303010) 열기

2. 새 Connector Application를 새로 만듭니다

3. OAuth 2.0 Flow를 Authorization Code로 지정합니다

4. https://<your-worker-url>/callback을 redirect URL로 추가합니다. (*.workers.dev 호스트나 사용자 지정 도메인을 사용 가능)

5. Client ID와 Client Secret을 기록해 둡니다. 배포할 때 이 값들을 secret으로 입력합니다.

여기에 scope 필드를 설정할 필요가 없습니다. OAuth scopes (api openid profile email offline_access, 그리고 Acumen이 refresh token을 발급하게 만드는 offline_access 포함)는 MCP서버가 인가 요청에 담아 전송하며, Connected Application에서 설정되지 않습니다.

접근 게이트: Canary Generic Inquiry (SM208000, SM201005)

사용자가 Anual Environment tools에 액세스하기 전에 로그인 흐름에서는 접근 게이트를 실행합니다. OData로 간단한 canary Generic Inquiry를 조회하여 해당 사용자의 토큰이 이 GI를 읽을 수 있는지 확인합니다(200 → 허용, 403 → 거부). 이때 Acumen 역할의 멤버십을 직접 검사하지 않고 "단순히이 Generic Inquiry 하나를 볼 수 있는가"를 확인합니다. canary GI의 읽기가 허용되는 사용자는 편한 방식으로 제한하면 됩니다. 권장되는 가장 깔끔한 방법은 마커 표시를 위한 별도 역할을 두는 것입니다.

1. 카나 서리 GI를 생성합니다. System > Customization > Generic Inquiry (SM208000) 를 열어 MCPAccess라는 이름의 GI를 만들고, 아무 테이블의 단일 필드 하나만 있는 단순한 목록을 사용합니다. Expose via OData 를 이용하눈 설정합니다.

2. 읽myself 대상자를 제한합니다 (권장: 마커 역할 사용). ** System > Access Rights > User Roles (SM201005)** 에서 MCPAccess 라는 역할을 만들고 해당 역할에는 GI 하나만 연결할 수 있습니다. 이 역할에 화면 권한은 부여하지 않고, 그 역할에만 MCPAccess GI를 할당한 다음, 사용자 AI 어시스턴트 액세스가 필요한 각 사용자에게 이 역할을 지정합니다. 그 외에 OData 읽기를 통해 GI 접근을 제어할 수 있다면 메커니즘이면 어떤 것으로도 무방합니다.

ACUMATICA_CANARY_GI 변수로 canary GI의 이름을 변경할 수 있습니다(기본값 mediocre **: MCPAccess). 설정은 Cloudflare 대시보드(Variables and Secrets) 또는 wrangler.jsonc에서 변경 합니다.

Generic Inquiry within AI exposure (strongly recommended)

A mature Acumatica 인스턴스에는 수백 개의 Generic Inquiry가 있을 수 있으며, 대부분 사람 화면(넓은 보고서 그리드, 대시보드, 임시 쿼리)용으로 만들어졌습니다. 그 모든 것을 어시스턴트에 노출하면 컨텍스트가 넘치고 잘못된 Inquiry를 선택하게 됩니다. 더 나쁜 것은, OData로 노출된 파라미터형 GI가 조용히 잘못된 데이터를 반환한다는 점입니다. 파라미터 없이 쿼리하면 Acumatica는 오류 없이 기본값/필터링되지 않은 행을 반환하며, 모델은 이를 감지할 수 없습니다. GI 노출 게이트(GI exposure gate) 는 이를옵트인 방식으로 바꿉니다. AI 에이전트가 쿼리하기에 실제로 유용그리고 올바른 GI에만 태그(ExposedToMCP)를 붙이면 모델은 그 GI 목록만 보게 됩니다.

이 게이트는 구성하기 전까지는 비활성화되어 있습니다. 서버가 실행되지만 레지스트리가 없으면 어시스턴트는 GI를 검색할 수 없습니다(acumatica_list_generic_inquiries는 아무것도 반환하지 않습니다. 여전히 정확한 이름으로 GI를 실행할 수는 있습니다). 이 게이트 목록을 구성하면 어시스턴트에게 안전하게 검색할 수 있는 정리된 GI 목록이 제공됩니다. 활성화는 일회성 Acumatica 사용자 정의 프로젝트로, acumatica/에 포함되어 있습니다. UsrExposedToMCP / UsrAIDescription(GI(Design)) 및 UsrResAIDescription(GIResult) 사용자 정의 필드와 SM208000 폼 변경을 추가합니다. 그리고 MCPGIs / MCPGIFields 피드 GI, MCP Access 역할의 피드 읽기 권한, 노출하려는 GI 태그 지정을 수행합니다. docs/generic-inquiries.md를 참조하세요.

전체적인 근거, 노출할 GI를 결정하는 방법 및 단계별 설정에 대해서는 Generic Inquiries 를 참고하세요.

사용자 지정 도메인(선택)

사용자 배포 시 기본 제공되는 *.workers.dev 호스트 이름이 제공됩니다. 브랜드 호스트 이름을 연결하려면:

• Cloudflare 대시보드를 통해: Workers & Pages → mcp4acumatica → Settings → Domains & Routes → Add 로 이동합니다. 도메인의 영역(zone)은 Cloudflare 계정에 있어야 합니다.

• wrangler.jsonc를 통해: 파일 상단의 routes 블록 주석을 해제하고 pattern과 zone_name을 편집한 후 다시 배포합니다.

호스트 이름을 변경하는 경우, 새로운 https://<host>/callback를 Connected Application의 SM303010 리다이렉트 URI에 추가하는 것을 잊지 마세요.

Connecting to Claude

Claude.ai / Claude Desktop

1. Settings > Connectors 로 이동합니다.

2. Add Connector 를 클릭하고 URL https://<your-worker-url>/mcp 를 입력합니다.

3. 처음 사용 시 Acumatica 로그인 페이지로 리디렉션됩니다.

4. 계정이 canary GI를 읽을 수 있는 경우(즉, 액세스 권한을 부여받은 경우) AI 데이터 처리에 대한 동의 페이지가 표시됩니다.

5. 동의를 확인하면 Claude가 49개 도구를 모두 사용할 수 있습니다.

Claude Code (CLI)

claude mcp add acumatica-erp --transport streamable-http https://<your-worker-url>/mcp

API(via Anthropic SDK)

Anthropic API와 함께 MCP를 사용하는 경우, MCP 클라이언트를 https://<your-worker>/mcp 로 가리킵니다. 서버는 /register에서 클라이언트 등록을 사용하는 OAuth 2.1을 지원합니다.

사용 가능한 도구

핵심

재무 / 회계

재고 및 창고

구매

프로젝트

서비스 및 필드

영업 및 CRM

발송 및 처리

HR 및 급여

CRM 활동

유틸리티 / 검색

팁: 먼저 acumatica_describe_entity를 사용하여 사용 가능한 필드를 파악한 다음, acumatica_list_entities를 사용하여 검색/필터링하세요. Generic Inquiry는 acumatica_list_generic_inquiries에서 GI 이름을 찾고, acumatica_describe_inquiry에서 필드 스키마를 확인하세요. 또 다른 사용 패턴은 docs/example-prompts.md를 참조하세요.

문서

상세 문서는 docs/ 폴더에 있습니다:

• 도구 참조 -- 49개 도구의 매개 변수와 엔드포인트 모두 상세.

• 예제 프롬프트 - 용도별 정리된 Claude 및 다른 MCP 클라이언트용 예제 프롬프트.

• OData 필터링 가이드 -- $filter, $orderby, $select, $expand, $top 쿼리 파라미터 가이드.

• Generic Inquiries -- GI가 AI용으로 게이트되는 이유, 노출할 GI, 옵트인 레지스트리 켜는 방법.

• 스키마 지식 -- 빌드 통합/사용자화를 위한 오프라인 스키마 검색 도구와 스키마 인덱스 생성 방법.

• 아키텍처 -- 상세 아키텍처, OAuth 흐름, 보안 모델, 설계 결정.

• 자체 호스팅 가이드 -- Cloudflare 외 Node.js 또는 기타 플랫폼에서 MCP 서버 실행 방법.

• Acumatica 업그레이드 안내 -- 연결된 Acumatica 버전 변경/업그레이드 시 취해야 할 절차.

스킬

이 저장소에는 재사용 가능한 Claude 스킬이 포함되어 있습니다. skills/에 제공됩니다:

• acumatica-gi-descriptions -- Generic Inquiry 및 그 결과 열에 대한 AI용 설명을 작성하는 전체 사이클 프로세스입니다. GI 이름을 추측하는 대신, GI 자체의 설계 메타데이터(테이블, 조인, WHERE 조건, 열)에 기반을 둡니다. 대규모 GI 메타데이터 작업이 조용히 실패시키는 플랫폼 함정, 탐색할 가치가 있는 설계 신호 체크리스트, 그리고 잘라내기 감사, 설계 브리핑, 초안 검증을 위한 세 개의 스크립트가 포함되어 있습니다.

사용하려면 Claude의 스킬 디렉터리를 가리키거나, 자신의 .claude/skills/에 복사하세요.

보안

• 저장된 자격 증명 없음. MCP 서버는 Acumatica 비밀번호를 저장하지 않습니다. OAuth 2.0 인가 코드 흐름을 사용하며, 사용자는 Acumatica에서 직접 인증합니다.

• 사용자별 토큰. 각 사용자의 Acumatica 액세스 토큰은 플랫폼 키-값 저장소(기본 배포 환경에서는 Cloudflare KV)에 사용자 이름별로 저장됩니다. 토큰은 만료되면 자동으로 갱신됩니다. 리프레시 토큰이 만료된 경우에는 수동 재연결 없이도 연결이 자동으로 재인증됩니다.

• 액세스 게이트. 지정된 카나리 역할의 Generic Inquiry를 읽을 수 있는 사용자만 연결할 수 있습니다. 서버는 로그인 시 역할 멤버십이 아닌 OData를 통한 GI 읽기 가능 여부를 확인합니다. 권한이 없는 사용자는 액세스 거부 페이지를 보게 됩니다. GI에 대한 접근은 원하는 대로 제한하면 됩니다. 권장하는 방식은 MCP Access 역할을 마커로 사용하는 것입니다. GI 이름은 ACUMATICA_CANARY_GI 환경 변수로 구성할 수 있습니다.

• 동의 중간 화면. 액세스 검사를 통과한 후, 사용자는 MCP 세션이 활성화되기 전에 자신의 데이터가 외부 AI 모델에 의해 처리된다는 사실을 인지하고 동의해야 합니다.

• 민감 필드 마스킹. 도구 응답은 자동으로 민감 필드 이름(SSN, 은행 계좌, 급여, 신용카드 등)을 검사하며, 일치하는 값은 [REDACTED]로 대체됩니다. 패턴은 REDACT_PATTERNS 및 REDACT_SKIP 환경 변수로 구성할 수 있습니다.

• 역할 기반 액세스. 사용자의 Acumatica 역할에 따라 읽을 수 있는 레코드가 결정됩니다. Acumatica에서 특정 레코드에 대한 액세스 권한이 없는 사용자는 MCP 서버를 통해서도 해당 레코드에 접근할 수 없습니다.

• 읽기 전용. 현재의 모든 도구는 읽기 전용 조회입니다. 어떤 데이터도 생성되거나, 수정되거나, 삭제되지 않습니다.

• 요청 속도 제한. 기본값은 동시 요청 3건, 분당 요청 40건, 쿼리당 레코드 1,000건 상한이며, 재배포 없이 /docs/admin/settings의 관리자 콘솔에서 모두 구성할 수 있습니다. 제한은 사용자별로 적용되며 도구 호출이 아닌 Acumatica에 대한 HTTP 호출을 기준으로 집계됩니다. 거부가 발생하면 정확한 retryAfterSeconds 값을 포함한 구조화된 응답이 반환되고 rate_limit_hit 이벤트로 기록되므로, 상한이 너무 낮게 설정되어 있는지 파악할 수 있습니다.

• 페이지네이션 거부. 목록/조회 도구(acumatica_list_entities, acumatica_run_inquiry, acumatica_list_generic_inquiries)는 페이지네이션을 지원하지 않습니다. 응답이 ACUMATICA_MAX_RECORDS 상한에 도달하면 도구는 truncated: true, paginationSupported: false, actionRequired: "..."를 포함한 구조화된 응답을 반환하여, AI가 더 많은 레코드를 가져오지 않고 멈춘 다음 사용자에게 더 좁은 필터를 요청하도록 안내합니다.

• 감사 로깅. 모든 도구 호출, 인증 이벤트(로그인 성공/거부, 동의 수락) 및 필드 마스킹 이벤트는 구조화된 JSON으로 기록됩니다. npx wrangler tail로 확인할 수 있습니다.

플랫폼 이식성

기본 배포 대상은 Cloudflare Workers이지만, 도구 핸들러와 핵심 라이브러리는 플랫폼에 종속되지 않습니다. 저장소 추상화 계층(IKeyValueStore 인터페이스 + AppEnv 타입)이 도구 로직을 Cloudflare 전용 API에서 분리하므로, Node.js에서 Redis, SQLite 또는 기타 저장소 백엔드를 사용하는 자체 호스팅 배포가 가능합니다. 자세한 내용은 셀프 호스팅 가이드를 참조하세요.

기술 스택

• 런타임: Cloudflare Workers + Durable Objects

• MCP: agents SDK (McpAgent), @modelcontextprotocol/sdk

• 인증: @cloudflare/workers-oauth-provider

• HTTP 라우팅: Hono

• 언어: TypeScript

• 검증: Zod

개발

npx wrangler dev       # Start local dev server
npx tsc --noEmit       # Type check
npx wrangler tail      # Stream live logs from deployed worker

라이선스

Apache 2.0 -- Copyright 2026 Hall Boys, Inc.