MCP로 AI 에이전트를 NetSuite에 연결하기: 모듈 패턴

문제: 4개의 API 표면과 정확도 격차

NetSuite는 단일 API가 아닙니다. 서로 다른 시대에 구축된 통합 표면의 모음이며, 각각 다른 능력과 제한을 가집니다. Truto의 NetSuite 통합 분석은 이를 "ERP의 최종 보스"라고 부릅니다 — 대부분의 팀이 복잡성을 수개월 단위로 과소평가합니다.

API 표면	최적 용도	제한 사항
SuiteQL	조인, 집계, 다중 테이블 쿼리가 포함된 복잡한 읽기	읽기 전용. 레코드 생성, 업데이트, 삭제 불가. 결과 세트 100,000행 상한.
SuiteTalk REST API	개별 레코드 CRUD (공급업체 생성, 구매 주문 업데이트)	필터링 제한적. 역사적으로 쓰기 요청당 1레코드. 동기 검증으로 인해 쓰기가 느림.
SOAP API	레거시 레코드 타입 (상세 세율 프로필)	폐지 예정. 2026.1부터 신규 엔드포인트 없음. 2028.2 완전 제거 예정.
RESTlets (SuiteScript)	커스텀 서버측 로직, PDF 생성, 동적 메타데이터	고객의 NetSuite 계정에 코드 배포 필요.

잘못된 표면을 선택하면 성능 병목이나 데이터 누락으로 이어집니다. 3-테이블 조인이 필요한 쿼리는 REST 레코드 API가 아닌 SuiteQL을 사용해야 합니다. 커스텀 검증이 필요한 쓰기는 일반 REST 엔드포인트가 아닌 RESTlet을 사용해야 합니다. 어느 표면을 호출해야 하는지 모르는 에이전트는 조용히 실패하거나 불완전한 결과를 반환합니다.

이 4개 표면 위에, Oracle은 2025년 8월에 NetSuite AI Connector Service를 발표했습니다 — Claude와 ChatGPT 같은 AI 클라이언트가 역할 기반 권한으로 NetSuite 데이터를 쿼리하고 조작할 수 있게 하는 자체 MCP 서버입니다. 공식 문서는 이를 Model Context Protocol (MCP)을 지원하는 프로토콜 기반 통합 서비스로 설명하며, 표준 도구 SuiteApp과 커스텀 도구용 프레임워크를 갖추고 있습니다.

자체 커넥터는 연결 문제를 해결합니다. 정확도 문제는 해결하지 않습니다.

정확도 격차: Oracle 자체의 경고

ONE Pacific의 "NetSuite AI 2026: What Works, What Doesn't"는 AI Connector Service 공식 FAQ의 "How accurate are the results" 항목에서 한 줄을 발견했습니다:

"AI may hallucinate. Always validate results against source data."

이것은 사용자 불만이 아닙니다. 벤더 자체의 인정입니다. 한 초기 도입자는 2025년 8월에 보고했습니다: "The revenue it gave is nowhere near what the actual revenue is for 2025. It was off by more than double what it is."

문제는 버그가 아닌 구조적입니다. AI는 실제 데이터를 쿼리합니다 — 숫자는 조작되지 않았습니다. 문제는 질문의 의미입니다. 재무 사용자가 "what is our revenue for 2025"라고 물을 때, AI에는 그 특정 비즈니스에 대해 어떤 GL 계정이 "revenue"를 구성하는지 알 방법이 없습니다. 프롬프트에 컨텍스트가 없으면, 찾은 것을 무엇이든 잡아서 자신감 있게 결과를 제시합니다.

실패 모드는 조용합니다:

• 잘못된 조인은 에러를 발생시키지 않습니다.
• 잘못된 날짜 필터는 에러를 발생시키지 않습니다.
• 누락된 자회사 제거는 에러를 발생시키지 않습니다.
• 올바른 것처럼 보이지만 실제로는 틀린 답을 받습니다.

이것이 시맨틱 레이어 격차입니다. 자체 커넥터는 AI에 원시 레코드에 대한 접근 권한을 줍니다. 그 레코드가 무엇을 의미하는지 AI에게 알려주지 않습니다. 재무 팀에 필요한 것은 똑똑함이 아니라 정확성입니다.

자체 커넥터가 잘 하는 일

ONE Pacific의 정직한 평가는 전적으로 부정적이지 않습니다. AI Connector에는 실제로 작동하는 작업 표면이 있습니다:

Cursor + NetSuite AI Connector는 기술 작업에 실용적입니다. Cursor(AI 네이티브 코드 에디터)를 MCP 커넥터와 페어링하면, 범용 앱의 Claude나 ChatGPT보다 쿼리 초안 작성, 스키마 탐색, ERD 스타일 매핑, 트랜잭션 워크플로 추적에 더 유용합니다. AI는 비즈니스 로직을 추측하는 것이 아니라 복잡한 시스템을 심문하는 것을 도울 때 빛납니다.

개발자 워크플로는 표준 실무입니다. Claude나 ChatGPT를 사용해 SuiteScript를 작성하고, 디버깅하고, 워크플로를 문서화하는 개발자는 이제 흔합니다 — 대부분의 팀은 이를 "AI 이니셔티브"로 조차 라벨링하지 않습니다.

n/llm 모듈은 2025.1 개발자 자료에 등장하여, AI를 커스텀 SuiteScript에 직접 임베드할 수 있게 했습니다. 도입은 얇지만 표면은 실재합니다.

ONE Pacific의 청중별 평결:

청중	평결
자연어 쿼리를 원하는 재무 사용자	아직 준비되지 않음. 정확도 위험은 실재하고 일관적임. 정확해야 하는 모든 것에 Power BI 또는 전용 FP&A 도구를 사용하세요.
개발자 및 기술 컨설턴트	오늘 설정 시간을 들일 가치가 있음. SuiteQL, 스키마 탐색, 워크플로 분석을 위한 Cursor + MCP.
컨설턴트	당분간 일자리는 안전하지만, AI를 무시하는 것이 진짜 위험입니다.
투자를 평가하는 모든 사람	올해 재무용 네이티브 AI는 베팅할 가치가 없습니다. 개발자 및 기술 도구는 설정에 투자하면 오늘부터 실재합니다.

중요한 설정 세부사항

세 가지 설정 과제가 작동하는 연결과 조용한 실패를 구분합니다.

역할 요구사항. 연결은 Administrator가 아닌 역할을 사용해야 합니다 — MCP Server Connection, OAuth 2.0 Access Tokens, 도구별 권한을 가진 커스텀 역할. 관리자가 Administrator 계정으로 설정하면 아무 일도 일어나지 않고 실패도 명확하지 않습니다. 관리자 설정은 조용히 실패합니다.

/all URL 접미사. 연결 URL에는 /all이 포함되어야 합니다:

https://<accountid>.suitetalk.api.netsuite.com/services/mcp/v1/all

/all 접미사가 없으면, 다른 모든 것이 올바르게 설정되어 있어도 연결이 끊어진 것으로 나타납니다. 초기 문서에서는 이것이 명확하지 않았고, Houseblend 트러블슈팅 가이드는 이것이 흔한 시간 낭비 문제임을 확인합니다.

SAML SSO 마찰. SAML 환경(Okta, Azure AD)은 OAuth 인증 중 역할 선택 문제를 겪을 수 있습니다 — AI Connector 역할이 나타나지 않을 수 있습니다. 조직이 SAML SSO를 사용하는 경우, 프로덕션 설정에 투자하기 전에 샌드박스 계정으로 조기에 검증하세요.

시맨틱 레이어: 커스텀 모듈이 제공하는 것

자체 커넥터는 AI에 데이터 접근 권한을 줍니다. 커스텀 MCP 모듈은 AI에게 그 데이터가 무엇을 의미하는지 이해를 줍니다. 이것이 시맨틱 레이어입니다 — 어떤 필드가 수익인지, 어떤 자회사 제거가 적용되는지, 어떤 날짜 필터가 유효한지, 어떤 조인이 특정 비즈니스에 올바른지 에이전트에게 알려주는 타입화된 스키마.

모듈 패턴은 MCP Module Code Standard를 따릅니다: 모든 도구는 타입화된 입력 스키마, 타입화된 출력 스키마, 속도 제한, 감사 로그, 에러 계약을 가집니다. 에이전트는 원시 테이블에 대한 자유 형식 SQL이 아닌, 구조화된 인수로 이름별로 도구를 호출합니다.

수익 쿼리를 생각해 보세요. 거버넌스된 모듈은 "임의의 SuiteQL 실행"을 도구로 노출하지 않습니다. 타입화된 작업을 노출합니다: get_revenue_summary(period, subsidiary, segment), get_vendor_balance(vendor_id, as_of_date), get_inventory_availability(item_ids, location_ids). 각 도구의 스키마는 비즈니스 의미를 인코딩합니다 — 어떤 GL 계정이 수익에 매핑되는지, 어떤 자회사 제거가 적용되는지, 어떤 날짜 범위가 유효한지. 에이전트는 올바른 답을 받습니다. 왜냐하면 묻는 질문이 비즈니스가 의미하는 질문이기 때문입니다.

이 패턴의 참조 구현은 4개의 API 표면을 통합 인터페이스 뒤에 래핑하는 SuiteTalk 커넥터입니다. RESTConnector 클래스는 OAuth 1.0 Token-Based Authentication (TBA)로 인증하며, HMAC-SHA256 서명을 사용합니다 — consumer key, token ID, 시크릿을 사용하여 각 HTTP 요청마다 고유한 서명을 계산합니다. SOAPConnector 클래스는 REST API가 다루지 않는 레거시 레코드 타입을 처리합니다. SOAPAdaptor는 REST 메타데이터 카탈로그가 노출하지 않는 선택 값과 커스텀 필드 매핑을 해결합니다. 커넥터는 작업별로 올바른 API 표면을 선택합니다: 읽기는 SuiteQL, 쓰기는 REST, 레거시 타입은 SOAP, 커스텀 로직은 RESTlets.

이것은 얇은 래퍼가 아닙니다. RESTConnector는 주소 해결(도시, 주, 우편번호, 국가별 청구지 및 배송지 주소 매칭과 폴백 매칭), 커스텀 필드 선택 값 조회(캐시된 매핑 또는 SOAP 폴백을 통해 표시 값을 내부 ID로 해결), 트랜잭션 항목 가격 책정(수량 임계값과 고객 세그먼트별 가격 수준 해결), 재고 약정 전략을 처리합니다. 이들 각각은 자체 커넥터가 원시 레코드 데이터에서 AI가 알아내도록 남겨둔 시맨틱 작업입니다.

인증: 운영상 제약

NetSuite의 인증 환경은 파편화되어 있으며, 선택에는 프로덕션 결과가 있습니다.

자체 AI Connector는 OAuth 2.0 Authorization Code Grant with PKCE를 사용합니다 — 안전하지만 특정 권한을 가진 Administrator가 아닌 역할이 필요합니다. OAuth 2.0 리프레시 토큰은 7일 후에 만료되어 수동 사용자 재동의가 필요합니다. 이것은 에이전트가 무인으로 실행되는 B2B 백그라운드 동기화에 허용되지 않습니다.

프로그래매틱 통합의 경우, Token-Based Authentication (TBA) — NetSuite의 OAuth 1.0a 스타일 방식 — 가 프로덕션 표준으로 남아 있습니다. TBA는 SOAP, REST, RESTlets에 걸쳐 작동하며, 만료되지 않고, 각 HTTP 요청마다 고유한 HMAC-SHA256 서명 계산이 필요합니다. 서명 베이스 문자열은 인증 버그의 가장 흔한 발생지입니다: HTTP_METHOD & percent_encode(BASE_URL) & percent_encode(SORTED_PARAMS). 샌드박스 함정 — 샌드박스 계정은 URL에 sb 접미사를 갖지만 OAuth realm 매개변수는 대문자와 밑줄이어야 합니다(123456_SB1) — 는 팀에게 며칠의 디버깅을 낭비하게 했습니다.

모듈 패턴은 이 복잡성을 격리합니다. 에이전트는 OAuth 서명을 구성하지 않습니다. 모듈의 도구 메서드는 인증을 내부적으로 처리하며, 프로그래매틱 접근에는 TBA를, MCP 서버 표면에는 OAuth 2.0을 사용합니다. 에이전트는 get_revenue_summary를 호출하고 모듈이 나머지를 처리합니다 — 서명 계산, 429 재시도, 에러 분류, 감사 로깅.

동시성 함정

NetSuite의 동시성 거버넌스는 순진한 에이전트 통합을 깨는 제약입니다. 모든 API 타입 — SuiteTalk REST, SOAP, SuiteQL, RESTlets, AI Connector Service — 가 하나의 동시성 풀을 공유합니다. 베이스 제한은 서비스 티어에 따라 다릅니다:

서비스 티어	계정 베이스 제한
Standard	5
Premium	15
Enterprise	20
Ultimate	20

각 SuiteCloud Plus 라이선스는 베이스에 10을 추가합니다. 5개의 SuiteCloud Plus 라이선스를 가진 Enterprise 계정은 65개의 동시 요청 제한을 가집니다. 기존 REST web services 통합에 20개가 할당된 경우, AI Connector는 나머지 45개만 사용할 수 있습니다.

제한을 초과하면 요청은 "Too Many Requests" 에러를 받고 클라이언트는 재시도해야 합니다. Standard 티어 계정(베이스 제한 5)에 대해 30개의 도구 호출을 병렬로 발사하는 에이전트는 그중 25개를 실패시킵니다. 모듈 패턴은 도구별 속도 제한으로 이를 해결합니다 — 각 도구는 등록 호출에서 자체 제한을 선언하고, 백본은 에이전트별, 도구별, 윈도우별로 이를 시행합니다. 제한에 도달하면 에이전트는 크래시가 아닌 Retry-After 헤더가 있는 구조화된 429 응답을 받습니다.

왜 이것이 일반화되는가

NetSuite 패턴 — 4개의 파편화된 API 표면, 정확도 격차가 있는 자체 MCP 서버, 벤더가 제공하지 않는 시맨틱 레이어 — 는 NetSuite에만 국한되지 않습니다. 동일한 구조가 ERP 및 CRM 환경 전체에 나타납니다:

• HubSpot에는 확장되는 능력을 가진 자체 Remote MCP 서버가 있습니다(2026년 6월 기준 content analytics, landing page creation), 하지만 커스텀 객체, 민감 데이터, 워크플로 자동화는 커스텀 모듈이 다뤄야 할 갭으로 남아 있습니다.
• Shopify에는 자체 Storefront MCP와 Google과 공동 개발한 Universal Commerce Protocol (UCP)이 있지만, 측정 문제 — "각 도구가 자신의 숙제를 채점한다, 귀속 수익은 실제의 187%에 달한다" — 는 시맨틱 레이어 격차의 커머스 등가물입니다.
• BigCommerce에는 Stripe와의 Agentic Commerce Suite (ACP)가 있어 MCP를 인텔리전스 레이어로 사용하지만, 3계층 아키텍처(Interaction to Intelligence to Commerce)는 여전히 비즈니스 의미를 프로토콜 호출에 매핑하는 타입화된 모듈이 필요합니다.

모듈 패턴은 모든 사례에서 동일합니다: 비즈니스 의미를 인코딩하는 타입화된 스키마, 플랫폼 제약을 존중하는 속도 제한, 모든 도구 호출을 재구성 가능하게 만드는 감사 로그, 그리고 에러 경로를 커버하는 테스트. MCP Module Code Standard가 구조를 정의합니다. NetSuite 커넥터는 가장 어려운 사례의 참조 구현입니다 — 벤더 자체의 FAQ가 모든 결과를 검증하라고 경고하는 사례입니다.

Gartner는 2027년까지 클라우드 ERP 지출의 62%가 AI 지원이 될 것이라고 예측합니다. 자체 커넥터는 개선될 것입니다. 시맨틱 레이어 격차는 좁아질 것입니다. 하지만 2026년에 프로덕션 에이전트를 출하하는 팀은 지금 타입화된 모듈 레이어를 구축하는 팀입니다 — 데이터의 의미를 AI에게 알려주는 레이어를, 어디서 찾을 수 있는지뿐만 아니라.

---

NetSuite, BigCommerce, 3개의 공급업체 카탈로그를 운영하는 유통업체는 이메일이나 포털로 RFQ를 수신하고, 카탈로그 그래프에 대해 제품을 해결하고, 고객 티어별로 가격을 책정하고, 동시성 제한을 준수하면서 NetSuite 재고 가용성을 확인하고, 올바른 API 표면을 통해 수락된 견적을 NetSuite에 다시 기록하는 에이전트를 얻습니다 — 그리고 모든 도구 호출은 타입화된 스키마, 속도 제한, 감사 로그를 가집니다. 그 빌드는 4단계 메서드의 2-3단계이며, 일반적으로 5-8주 내에 라이브됩니다.

스코프가 정의된 빌드를 요청하세요. 1주일 Discovery. 시스템 인벤토리, 워크플로 맵, 고정 스코프를 받습니다 — 당사와 빌드하는지 여부와 관계없이.