Salesforce Headless MCP AI

운영 환경에 적합한 Frappe v15+ 애플리케이션으로, 구성 가능한 AI 제공자와 Salesforce Hosted MCP를 기반으로 하는 웹 AI 어시스턴트를 승인된 각 Frappe 사용자에게 제공합니다. Salesforce OAuth 토큰과 AI API 키는 Frappe 서버에 암호화되어 저장되며, 브라우저 코드는 허용된 Frappe 메서드만 호출합니다.

Salesforce Hosted MCP는 현재 Salesforce Beta 서비스입니다. 운영 사용 전에 조직의 가용성, 제한 사항 및 약관을 확인하세요.

(이미지 URL은 그대로 유지)

프로젝트 문서

• 개발 기술 문서

• 프로젝트 프레젠테이션 스크립트

Related MCP server: Salesforce MCP Server

아키텍처

Frappe browser page (/salesforce-ai)
        ↓ authenticated frappe.call
Frappe Python services
        ├── OpenAI / Claude / Gemini / Azure / local LLM (tool calling)
        └── Salesforce Hosted MCP (Streamable HTTP + OAuth bearer token)
                    ↓
              Salesforce org

MCP 도구 목록은 런타임에 검색됩니다. 읽기 전용 모드에서 서버는 discover, describe, dispatch_readonly만 노출하며, dispatch는 모델의 도구에서 제거되고 Python에서 독립적으로 차단됩니다. 쓰기 작업이 활성화되면 dispatch는 10분 동안 사용자별 바인딩된 확인 기록에 보관됩니다.

이 앱은 Salesforce SObject 서버도 지원합니다. platform/sobject-all의 경우 읽기 전용 모드에서는 읽기 전용으로 표시된 도구만 노출하며(Salesforce의 알려진 스키마/쿼리/검색/식별/관계 도구 포함), 쓰기 작업이 활성화되면 발견된 모든 변경 도구가 노출되고 모든 생성/업데이트/삭제 호출은 동일한 확인 게이트를 거칩니다.

요구 사항

• Frappe Framework v15 이상 및 작동하는 Bench 사이트

• Python 3.10+

• Headless 360이 활성화된 Salesforce 조직 (API v67.0 이상)

• OAuth Authorization Code + PKCE S256용으로 구성된 Salesforce External Client App

• 선택한 모델에 액세스할 수 있는 OpenAI API 키

• 공용 Frappe 사이트용 HTTPS

Python 종속성(httpx, openai)은 pyproject.toml에 선언되어 있으며 앱과 함께 설치됩니다.

설치

cd ~/frappe-bench
bench get-app https://github.com/TechwithZakir/salesforce_mcp_ai
bench --site yoursite.example install-app salesforce_mcp_ai
bench --site yoursite.example migrate
bench build --app salesforce_mcp_ai
bench restart

Salesforce MCP Manager를 Salesforce MCP User에 할당하세요. 워크숍 사용자에게는 Salesforce MCP Manager 또는 System Manager 역할을 할당하세요. 관리자는 Salesforce MCP 설정을 열고 구성을 저장한 후 /salesforce-ai로 이동합니다.

개발 환경의 경우:

cd ~/frappe-bench
bench new-app salesforce_mcp_ai
# Replace the generated app with this repository, or clone it into apps/salesforce_mcp_ai.
bench --site development.localhost install-app salesforce_mcp_ai
bench --site development.localhost migrate
bench build --app salesforce_mcp_ai

Salesforce MCP Manager 역할을 가진 관리자에게 Salesforce MCP User 역할을 할당하고, Salesforce MCP Manager 역할을 설정 관리자에게 할당하세요. 워크숍 사용자에게는 Salesforce MCP User 역할만 할당하는 것이 좋습니다.

기존 설치를 업그레이드한 후 bench --site yoursite clear-cache를 실행하고, 그런 다음 Desk에서 Salesforce MCP AI 작업 공간이 Salesforce MCP User, Salesforce MCP Manager, System Manager 역할이 할당된 사용자에게 표시됩니다.

Salesforce 설정

1. MCP Servers를 검색합니다.

2. MCP Servers를 선택하고 headless-360을 찾아 활성화합니다.

3. External Client App Manager로 이동하여 External Client App을 생성합니다.

4. OAuth Authorization Code 흐름을 활성화하고 PKCE S256을 요구합니다.

5. 범위 mcp_api, refresh_token, offline_access를 추가합니다(사용 중인 Salesforce 릴리스에서 노출되는 옵션 사용).

6. 콜백 URL을 정확히 다음으로 설정합니다.

https://YOUR-FRAPPE-DOMAIN/api/method/salesforce_mcp_ai.api.auth.salesforce_callback

7. 앱 정책에서 요구하는 경우 소비자 키와 클라이언트 시크릿을 Salesforce MCP Settings에 복사합니다.

Salesforce는 모든 MCP 작업에 대해 연결된 사용자의 CRUD, 필드 수준 보안, 공유 및 권한 설정을 적용합니다. 워크숍 사용자에게 필요한 Salesforce 권한만 부여하십시오.

아키텍처

Frappe browser page (/salesforce-ai)
        ↓ authenticated frappe.call
Frappe Python services
        ├── OpenAI / Claude / Gemini / Azure / local LLM (tool calling)
        └── Salesforce Hosted MCP (Streamable HTTP + OAuth bearer token)
                    ↓
              Salesforce org

MCP 도구 목록은 런타임에 가져옵니다. 읽기 전용 모드에서는 서버가 discover, describe, dispatch_readonly만 노출하며, dispatch는 모델의 도구에서 제거되고 Python에서 독립적으로 차단됩니다. 쓰기 작업이 활성화되면 dispatch는 10분 동안 사용자별 바인딩된 확인 기록에 보관되어 사용자가 명시적으로 확인할 때까지 유지됩니다.

또한 이 앱은 Salesforce SObject 서버도 지원합니다. platform/sobject-all의 경우 읽기 전용 모드에서는 읽기 전용으로 표시된 도구만 노출됩니다(그 외 Salesforce의 알려진 스키마/쿼리/검색/식별/관계 도구 포함). 쓰기 작업이 활성화되면 발견된 변경 도구가 노출되고 모든 생성/업데이트/삭제 호출은 동일한 확인 게이트를 거칩니다.

요구 사항

• Frappe Framework v15 이상 및 작동 중인 Bench 사이트

• Python 3.10+

• API v67.0 이상 및 Headless 360이 활성화된 Salesforce 조직

• OAuth Authorization Code + PKCE S256용으로 구성된 Salesforce External Client App

• 구성된 모델에 접근할 수 있는 OpenAI API 키

• 공개 Frappe 사이트용 HTTPS

Python 종속성(httpx, openai)은 pyproject.toml에 선언되어 있으며 앱과 함께 설치됩니다.

설치

cd ~/frappe-bench
bench get-app https://github.com/TechwithZakir/salesforce_mcp_ai
bench --site yoursite.example install-app salesforce_mcp_ai
bench --site yoursite.example migrate
bench build --app salesforce_mcp_ai
bench restart

관리자에게 Salesforce MCP Manager 역할을, 사용자에게 Salesforce MCP User 역할을 할당하십시오. Salesforce MCP 설정을 열고 설정을 저장한 후 /salesforce-mcp로 이동하십시오.

cd ~/frappe-bench
bench new-app salesforce_mcp_ai
# Replace the generated app with this repository, or clone it into apps/salesforce_mcp_ai.
bench --site development.localhost install-app salesforce_mcp_ai
bench --site development.localhost migrate
bench build --app salesforce_mcp_ai

로컬 개발의 경우:

https://YOUR-FRAPPE-DOMAIN/api/method/salesforce_mcp_ai.api.auth.salesforce_callback

Salesforce MCP 설정에서 관리자에게 Salesforce MCP Manager 역할을, 사용자에게 Salesforce MCP User 역할을 할당하십시오. 매니저로 설정을 저장한 후 /salesforce-mcp를 여십시오.

Enabled:                         On
AI Provider:                     OpenAI
API Key:                         (encrypted)
Model:                           gpt-5.6
Temperature:                     0.2
Max Tokens:                      4000
Salesforce Login URL:            https://login.salesforce.com
Salesforce MCP URL:              https://api.salesforce.com/platform/mcp/v1/platform/headless-360
Allow Write Operations:          Off
Require Write Confirmation:      On
Enable MCP Trace:                On
Enable Audit Logging:            On
Maximum MCP Tool Calls:          6
Request Timeout:                 60

기존 설치를 업그레이드한 경우 bench migrate를 실행하십시오.

설치

Salesforce Login URL: https://test.salesforce.com
Salesforce MCP URL:   https://api.salesforce.com/platform/mcp/v1/sandbox/platform/headless-360

Salesforce MCP AI 워크벤치가 Frappe 데스크에 나타납니다.

구성

Salesforce MCP 설정에서:

Production/Developer org: https://api.salesforce.com/platform/mcp/v1/platform/sobject-all
Sandbox/Scratch org:      https://api.salesforce.com/platform/mcp/v1/sandbox/platform/sobject-all

참고: Salesforce OAuth 토큰과 AI API 키는 Frappe 서버에 암호화되어 저장되며 브라우저로 전송되지 않습니다.

Salesforce 연결

사용자는 /salesforce-mcp 페이지에서 "Salesforce에 연결"을 클릭하여 OAuth 흐름을 시작할 수 있습니다. 승인 후 콜백은 토큰을 저장하고 연결을 생성합니다.

Ollama:    http://127.0.0.1:11434/v1
LM Studio: http://127.0.0.1:1234/v1
LiteLLM:   https://llm.example.com/v1
vLLM:      https://vllm.example.com/v1

사용

1. /salesforce-mcp를 엽니다.

2. "Salesforce에 연결"을 클릭합니다.

3. 모델을 선택하고 메시지를 입력합니다.

4. 쓰기 작업이 필요한 경우 "승인" 버튼을 클릭하여 확인합니다.

권한

• Salesforce MCP 사용자: 도우미를 사용하고, 자신의 Salesforce 계정을 연결/연결 해제하고, 자신의 로그만 볼 수 있습니다.

• Salesforce MCP 관리자: 설정을 구성하고 모든 감사 로그 및 연결을 볼 수 있습니다. 비밀 값은 API로 반환되지 않습니다.

DocType 권한 훅과 각 허용 메서드의 필터를 통해 소유권이 적용됩니다.

테스트 및 검증

테스트는 목(mock)을 사용하며 실제 Salesforce 조직이나 OpenAI 호출이 필요하지 않습니다.

bench --site development.localhost run-tests --app salesforce_mcp_ai
bench --site development.localhost migrate
bench build --app salesforce_mcp_ai

테스트 범위에는 PKCE, 일회성 OAuth 상태, 토큰 갱신, 읽기 전용 도구 필터링 및 차단, 연결/로그 소유권, 도구 호출 제한 설정이 포함됩니다. 릴리스 전에 /salesforce-mcp에 대한 브라우저 스모크 테스트도 수행하십시오.

소스 구조

salesforce_mcp_ai/
├── api/          # whitelisted auth, MCP, and agent methods
├── services/     # OAuth, token, MCP transport, OpenAI orchestration
├── utils/        # PKCE, validation, redaction
├── salesforce_mcp_ai/doctype/
├── tests/
└── www/salesforce-ai/

라이선스

MIT