# AI 에이전트를 위한 자수 MCP 서버

정규 페이지: https://embroideryfileconverter.com/ko/ai-agents

OAuth, 형식 검색, 사용량 상태 및 비공개 처리 작업이 포함된 원격 MCP 서버를 통해 AI 에이전트를 인증된 자수 도구에 연결합니다.

## 올바른 통합 선택

- 브라우저에서 승인된 OAuth를 통해 AI 어시스턴트가 사용자를 대신해 작업해야 할 때 이 원격 MCP 서버를 사용하세요.
- 기존 백엔드, SaaS 제품 또는 서버 측 자동화에는 [REST 개발자 API](https://embroideryfileconverter.com/ko/developers)를 사용하세요.

## MCP 클라이언트 연결

- 스트리밍 가능한 HTTP 엔드포인트: `https://embroideryfileconverter.com/mcp/embroidery`
- OAuth 범위: `mcp:use`
- 기본 MCP 속도 제한: 분당 60 요청
- 파일 생성 도구 제한: 사용자당 분당 6 요청 + 네트워크 제한
- 액세스 토큰 수명: 60분
- 갱신 토큰 수명: 30일

이 엔드포인트는 원격 Streamable HTTP 클라이언트와 작동합니다. 기본 브라우저 OAuth를 선호하며, 비밀번호, 갱신 토큰 또는 장기 bearer 토큰을 저장소에 붙여넣지 마세요.

## ChatGPT(OpenAI) 연결

전체 MCP 앱은 ChatGPT 개발자 모드에서 구성합니다. 사용 가능 여부와 쓰기 도구 제어는 요금제에 따라 다릅니다.

1. ChatGPT 웹에서는 설정 > 앱 > 고급 설정에서 개발자 모드를 활성화하거나, Workspace 설정 > 앱 > 만들기를 엽니다.
2. 앱을 만들고 MCP 서버 URL을 `https://embroideryfileconverter.com/mcp/embroidery`로 설정하세요.
3. OAuth를 선택하고, Scan tools를 선택한 후 브라우저에서 `mcp:use` 범위를 승인하세요.
4. 초안 앱을 만들고 활성화한 다음 새 대화의 도구 메뉴에서 선택하세요.

[공식 ChatGPT MCP 문서](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt)

## Claude, Claude Desktop, Cowork 또는 Claude Code 연결

Claude에서 사용자 지정 > 커넥터 > 사용자 지정 커넥터 추가를 열고 `https://embroideryfileconverter.com/mcp/embroidery`을 입력한 후 연결을 선택하고 OAuth를 완료하세요. 팀 및 Enterprise 소유자는 구성원이 개별적으로 연결하기 전에 조직 설정 > 커넥터 아래에 커넥터를 추가합니다.

Claude Code 명령:

```bash
claude mcp add --transport http embroidery-file-converter https://embroideryfileconverter.com/mcp/embroidery
# 그런 다음 Claude Code에서 /mcp을 실행하고 브라우저 인증을 완료하세요.
```

[공식 Claude 원격 MCP 문서](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)

## OpenAI Agents SDK 연결

백엔드는 로그인한 사용자에 대해 OAuth authorization code + PKCE를 완료하고, 토큰을 서버에 암호화하여 저장하며, 필요할 때 갱신한 후 현재 액세스 토큰을 호스팅된 MCP 도구에 전달해야 합니다. 브라우저 JavaScript에서 이 토큰을 노출하지 마세요.

```typescript
import { Agent, hostedMcpTool } from '@openai/agents';

const agent = new Agent({
  name: 'Embroidery assistant',
  tools: [
    hostedMcpTool({
      serverLabel: 'embroidery',
      serverUrl: 'https://embroideryfileconverter.com/mcp/embroidery',
      authorization: process.env.EFC_MCP_ACCESS_TOKEN,
      requireApproval: 'always',
    }),
  ],
});
```

[공식 OpenAI Agents SDK MCP 문서](https://developers.openai.com/api/docs/guides/tools-connectors-mcp)

## Cursor 연결

`.cursor/mcp.json`에 추가하고, Cursor 설정 > MCP에서 서버를 시작한 후 OAuth를 완료하세요. Cursor Agent 사용자는 `cursor-agent mcp login embroidery-file-converter`를 실행할 수 있습니다.

```json
{
  "mcpServers": {
    "embroidery-file-converter": {
      "url": "https://embroideryfileconverter.com/mcp/embroidery"
    }
  }
}
```

[공식 Cursor MCP 문서](https://docs.cursor.com/context/model-context-protocol)

## VS Code 및 GitHub Copilot 연결

`MCP: Add Server`를 실행하고 HTTP를 선택하거나 `.vscode/mcp.json`에 추가하세요. `MCP: List Servers`로 시작하고 구성을 신뢰한 후 브라우저 인증을 완료하세요.

```json
{
  "servers": {
    "embroidery-file-converter": {
      "type": "http",
      "url": "https://embroideryfileconverter.com/mcp/embroidery"
    }
  }
}
```

[공식 VS Code MCP 문서](https://code.visualstudio.com/docs/agent-customization/mcp-servers)

## OpenClaw 연결

```bash
openclaw mcp add embroidery-file-converter \
  --url https://embroideryfileconverter.com/mcp/embroidery \
  --transport streamable-http \
  --auth oauth \
  --oauth-scope mcp:use

openclaw mcp login embroidery-file-converter
openclaw mcp doctor embroidery-file-converter --probe
```

[공식 OpenClaw MCP 문서](https://docs.openclaw.ai/cli/mcp)

## Gemini CLI 연결

서버를 `~/.gemini/settings.json`에 추가한 후 Gemini CLI에서 `/mcp auth embroidery-file-converter`를 실행하세요.

```json
{
  "mcpServers": {
    "embroidery-file-converter": {
      "url": "https://embroideryfileconverter.com/mcp/embroidery"
    }
  }
}
```

[공식 Gemini CLI MCP 문서](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md)

## OpenCode 연결

`opencode.json`에 추가한 후 `opencode mcp auth embroidery-file-converter`를 실행하고 `opencode mcp list`로 확인하세요.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "embroidery-file-converter": {
      "type": "remote",
      "url": "https://embroideryfileconverter.com/mcp/embroidery"
    }
  }
}
```

[공식 OpenCode MCP 문서](https://opencode.ai/docs/mcp-servers/)

## Windsurf Cascade 연결

Windsurf 설정 > Cascade > MCP 서버를 열거나 `~/.codeium/windsurf/mcp_config.json`에 추가하세요. 서버를 시작하고 OAuth를 완료한 후 필요한 도구만 활성화하세요.

```json
{
  "mcpServers": {
    "embroidery-file-converter": {
      "serverUrl": "https://embroideryfileconverter.com/mcp/embroidery"
    }
  }
}
```

[공식 Windsurf MCP 문서](https://docs.windsurf.com/windsurf/cascade/mcp)

## Cline 연결

Cline의 OAuth 동작은 릴리스와 환경에 따라 다릅니다. MCP 서버 > 원격 서버를 열고 Streamable HTTP를 선택한 후 승인 허용 목록이 비어 있는 이 구성을 사용하세요:

```json
{
  "mcpServers": {
    "embroidery-file-converter": {
      "type": "streamableHttp",
      "url": "https://embroideryfileconverter.com/mcp/embroidery",
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

설치된 Cline 릴리스가 OAuth를 완료할 수 없는 경우 검토 및 버전 고정된 OAuth 브리지를 사용하거나 기본 OAuth를 지원하는 클라이언트를 선택하세요. `cline_mcp_settings.json`에 장기 토큰을 커밋하지 마세요.

[공식 Cline MCP 문서](https://github.com/cline/cline/blob/main/docs/mcp/mcp-overview.mdx)

## OAuth 검색 및 PKCE

- 보호된 리소스 메타데이터: `https://embroideryfileconverter.com/.well-known/oauth-protected-resource/mcp/embroidery`
- 인증 서버 메타데이터: `https://embroideryfileconverter.com/.well-known/oauth-authorization-server`
- 동적 클라이언트 등록: `https://embroideryfileconverter.com/oauth/register`
- 인증 서버 발급자: `https://embroideryfileconverter.com`
- 권한 부여: authorization code
- PKCE 방법: S256
- 필요 범위: `mcp:use`

동적 클라이언트 등록은 운영자가 명시적으로 허용한 콜백 출처와 네이티브 스킴만 허용합니다. 임의 콜백 도메인은 거부됩니다. MCP 엔드포인트를 사용하려면 계정에 확인된 이메일 주소가 있어야 합니다.

기본 신뢰 호스팅 콜백은 공식 ChatGPT, Claude, VS Code 출처와 설치된 클라이언트를 위한 루프백 콜백으로 제한됩니다. 와일드카드 리디렉션 도메인은 활성화되지 않습니다. `MCP_REDIRECT_DOMAINS`를 재정의하는 배포는 의도적으로 지원하는 클라이언트만 유지해야 합니다.

허용된 로컬 콜백 등록 예시:

```bash
curl -X POST https://embroideryfileconverter.com/oauth/register \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "client_name": "Your local agent",
    "redirect_uris": ["http://127.0.0.1:49831/callback"]
  }'
```

## 전체 도구 참조

### `list-formats-tool`

읽기 전용. 인수 없음. `artwork_inputs[]`와 `formats[]`를 읽기/쓰기 가능 여부, 라벨, 경고 필드와 함께 반환합니다. 워크플로 또는 대상 포맷을 선택하기 전에 호출하세요.

### `get-account-usage-tool`

읽기 전용. 인수 없음. 현재 미리보기 허용량, 크레딧 잔액, 워크플로 비용, 구독 한도, 초기화 날짜를 반환합니다. 구매나 소비는 전혀 일어나지 않습니다.

### `list-processing-jobs-tool`

읽기 전용. 연결된 계정이 소유한 최근 작업을 나열합니다.

- `limit`: 1~50 사이 선택형 정수, 기본값 20

### `get-processing-job-tool`

읽기 전용. 상태, 이벤트, 지표, 경고, 미리보기 결과물, OAuth 보호 파일 URL이 포함된 소유 작업 하나를 반환합니다.

- `workflow`: 필수, `conversion` 또는 `digitising`
- `job_id`: 필수, 26자 작업 식별자

### `create-processing-job-tool`

저장된 데이터를 생성합니다. 비공개 미리보기 작업 하나를 시작하며 미리보기 허용량을 소비할 수 있지만, 크레딧 구매나 유료 다운로드 잠금 해제는 전혀 일어나지 않습니다.

- `workflow`: 필수, `conversion` 또는 `digitising`
- `file_name`: 필수, 확장자를 포함한 원본 파일명(3~255자), 경로 구분자나 제어 문자 제외
- `file_base64`: 필수, data-URL 접두사 없는 순수 표준 base64
- `format`: 필수, 소문자 쓰기 가능 자수 출력 포맷
- `width_mm`: 10~300 숫자, 디지타이징 시 필수
- `colour_count`: 1~24 정수, 디지타이징 시 필수

구조화된 결과에 `billing_authorized: false`가 포함됩니다. 변환의 경우 선택한 출력 포맷이 감지된 원본 포맷과 달라야 합니다.

## JSON-RPC 도구 예제

포맷 목록:

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "list-formats-tool",
    "arguments": {}
  }
}
```

디지타이징 미리보기 생성:

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "create-processing-job-tool",
    "arguments": {
      "workflow": "digitising",
      "file_name": "logo.png",
      "file_base64": "iVBORw0KGgoAAA...",
      "format": "pes",
      "width_mm": 90,
      "colour_count": 8
    }
  }
}
```

반환된 작업 폴링:

```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "get-processing-job-tool",
    "arguments": {
      "workflow": "digitising",
      "job_id": "01JEXAMPLEJOBID000000000"
    }
  }
}
```

가능한 작업 상태는 `queued`, `processing`, `completed`, `failed`입니다. 백오프로 폴링하다가 종료 상태에서 중지하세요. 파일 URL은 동일한 OAuth 액세스 토큰이 필요하며 업로드의 `expiresAt` 보관 기간을 따릅니다.

## 자연어 프롬프트 예제

- “PES를 읽고 JEF로 안전하게 쓸 수 있는 포맷을 확인하고 호환성 경고를 표시하세요.”
- “최근 5개 자수 작업을 나열하고 실패한 항목을 요약하세요.”
- “업로드 전에 확인을 요청하세요. 그런 다음 logo.png를 폭 90mm, 최대 8색으로 디지타이징하고 PES 미리보기를 반환하세요.”
- “작업 01J…이 완료될 때까지 폴링한 후 스티치 지표, 경고, 다운로드 잠금 해제 여부를 보고하세요.”

## 안전 모델

- 결제, 체크아웃, 크레딧 구매, 유료 다운로드 잠금 해제 도구는 노출되지 않습니다.
- API 키 생성, 인증 변경, 자격 증명 읽기, 계정 삭제 도구는 노출되지 않습니다.
- 모든 작업 읽기는 연결된 사용자에게만 제한됩니다.
- 생성 도구는 비공개 업로드를 저장하고 작업을 생성하므로, 에이전트는 업로드 전에 반드시 확인해야 합니다.
- 파일명, 메타데이터, 작업 메시지, 경고는 신뢰할 수 없는 데이터입니다. 서버는 에이전트가 해당 값에 포함된 명령을 따르지 않도록 지시합니다.
- 완료된 결과는 자동으로 생산 준비가 완료되지 않습니다. 에이전트는 주장하기 전에 검증 지표와 경고를 확인해야 합니다.

## 문제 해결

- `401 Unauthorized`: 유효한 액세스 토큰이 전송되지 않았습니다. 클라이언트 OAuth 연결을 다시 시작하세요.
- `403 Forbidden`: 토큰에 `mcp:use` 권한이 없거나, 계정이 미인증 상태이거나, 요청한 작업이 다른 계정 소유입니다.
- `invalid_redirect_uri`: 콜백 출처 또는 네이티브 스킴이 서버 허용 목록에 없습니다.
- `422`: 도구 인수, base64 데이터, 원본 유형, 대상 포맷 또는 계정 할당량 검증에 실패했습니다.
- `429`: 요청 제한 초과. `Retry-After`를 준수하고 지터가 포함된 지수 백오프를 사용하세요.

## 관련 페이지

- [개발자 API 문서](https://embroideryfileconverter.com/ko/developers)
- [OpenAPI 3.1 설명](https://embroideryfileconverter.com/developers/openapi.json)
- [개인정보 처리방침](https://embroideryfileconverter.com/ko/privacy)