> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alforse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AI 어시스턴트 연결(MCP)

> 브라우저에서 권한을 부여하거나 API 키를 사용하여 Claude, ChatGPT, Cursor, VS Code 또는 다른 MCP 클라이언트를 Alforse 회사에 연결합니다.

Alforse는 Model Context Protocol(MCP) 서버를 운영하므로, AI 어시스턴트가 품목, 판매, 구매, 생산, 재고, 품질, 회계 등 ERP 데이터를 조회하고 다룰 수 있습니다. 회사의 누구나 자신의 어시스턴트를 연결할 수 있고, 개발자는 코딩 클라이언트와 스크립트를 연결할 수 있습니다. 어시스턴트는 연결된 사람 또는 키에 허용된 작업만 수행할 수 있습니다.

## 필요한 것

| | 값 |
| - | - |
| 서버 URL | `https://app.alforse.com/api/mcp` |
| 전송 방식 | Streamable HTTP(`POST`만 지원) |
| 플랜 | **Business**. 다른 플랜에서는 서버가 모든 호출을 거부합니다([제한](#limits) 참조). |
| 서버 매니페스트 | `https://app.alforse.com/.well-known/mcp.json` (공개, 회사 데이터 없음) |

어시스턴트를 로그인시키는 방법은 두 가지입니다. 사용하는 클라이언트가 지원하는 방법을 선택하십시오.

| 클라이언트 | 연결 방식 |
| - | - |
| Claude.ai, Claude Desktop, ChatGPT | **브라우저 권한 부여(OAuth).** 키를 만들거나 붙여 넣을 필요가 없습니다. |
| Claude Code | 둘 다 가능합니다. 키를 생략하면 처음 사용할 때 브라우저 권한 부여가 시작되며, API 키를 전달해도 됩니다. |
| Cursor, VS Code, Codex, 스크립트 및 CI | `Authorization` 헤더의 **API 키** |
| 로컬(stdio) 서버만 실행하는 클라이언트 | `mcp-remote`를 통한 API 키 |

## 브라우저 권한 부여로 연결

Alforse에서 먼저 설정할 것은 없습니다. 어시스턴트에 서버 URL을 추가하면 Alforse가 연결 승인을 요청합니다.

**어시스턴트에 서버를 추가합니다.**

* **Claude Desktop / Claude.ai:** **Settings → Connectors → Add custom connector**를 선택한 다음 `https://app.alforse.com/api/mcp`를 붙여 넣습니다.
* **ChatGPT:** **Settings → Connectors → Add**를 선택한 다음 같은 URL을 붙여 넣습니다. ChatGPT는 일부 플랜에서만 커스텀 커넥터를 제공합니다.
* **Claude Code:** `claude mcp add --transport http alforse https://app.alforse.com/api/mcp` (`--header` 없음).

**Alforse에 로그인합니다.** 어시스턴트가 브라우저에서 Alforse 페이지를 엽니다. 요청되면 로그인합니다.

**요청을 검토합니다.** **애플리케이션 권한 부여**(Authorize Application) 페이지에 어시스턴트의 이름과 돌아갈 웹사이트가 표시되고, 이어서 "is requesting access to your Alforse account."(Alforse 계정에 대한 액세스를 요청하고 있습니다.)가 표시됩니다. 그 아래에서 요청된 **범위**(Scope, `mcp:tools`)를 볼 수 있습니다.

**회사를 선택합니다.** **회사**(Company)에서 어시스턴트가 작업할 회사를 고릅니다. 한 회사에만 속해 있으면 선택 없이 그 회사가 표시됩니다. 하나의 연결은 정확히 한 회사에서만 작동합니다. 다른 회사에서 작업하려면 다시 연결하여 그 회사를 선택하십시오.

**권한 부여를 선택합니다.** 브라우저가 어시스턴트로 돌아가며 이제 연결되어 있습니다. "최근 수주 5건을 나열해 줘"처럼 간단한 질문으로 확인해 보십시오.

NOTE

**권한을 부여할 수 있는 사람**

**애플리케이션 권한 부여** 페이지에는 현재 회사의 **설정**에 대한 **업데이트** 권한이 필요합니다. 권한이 없으면 "Access Denied"(접근 거부)와 함께 앱으로 돌아갑니다. 관리자에게 권한을 요청하거나, 관리자가 만들어 주는 [API 키](https://docs.alforse.com/ko/docs/building/api-keys.md)를 사용하십시오.

### 연결로 할 수 있는 일

* 선택한 회사에서 **사용자 본인으로서**, 현재 [권한](https://docs.alforse.com/ko/docs/reference/permissions.md)과 정확히 같은 범위로 작동합니다. 권한이 바뀌면 어시스턴트의 권한도 함께 바뀝니다.
* 해당 회사의 활성 구성원이 아니게 되면 작동을 멈춥니다.
* 회사와 사용자는 항상 연결 자체에서 결정됩니다. 어시스턴트가 다른 인수를 전달해 회사를 바꾸거나 다른 사람으로 행동할 수 없습니다.

### 로그인의 내부 동작 방식

클라이언트가 이를 자동으로 처리합니다. 자체 클라이언트를 만드는 개발자를 위해 세부 사항을 여기에 기재합니다.

| 단계 | 엔드포인트 |
| - | - |
| 토큰 없는 호출에는 `401`과 `WWW-Authenticate: Bearer resource_metadata="https://app.alforse.com/.well-known/oauth-protected-resource"`로 응답합니다 | `/api/mcp` |
| 보호된 리소스 메타데이터 | `https://app.alforse.com/.well-known/oauth-protected-resource` |
| 인증 서버 메타데이터 | `https://app.alforse.com/.well-known/oauth-authorization-server` |
| 클라이언트 등록(개방형 동적 등록, `client_name`과 `redirect_uris`가 있는 JSON 본문) | `https://app.alforse.com/register` |
| 승인 페이지 | `https://app.alforse.com/authorize` |
| 토큰 교환 및 갱신 | `https://app.alforse.com/token` |

* 그랜트 유형: `authorization_code`와 `refresh_token`. 응답 유형: `code`.
* `S256` PKCE. 공개 클라이언트(토큰 엔드포인트 인증 방식 `none`)는 코드 챌린지를 보내야 합니다.
* 토큰 엔드포인트의 클라이언트 인증: `client_secret_post` 또는 `none`.
* 범위: `mcp:tools`.
* 인증 코드는 10분간 유효하며 한 번만 사용할 수 있습니다. 액세스 토큰은 1시간 동안 유효하며(`expires_in: 3600`), 클라이언트가 리프레시 토큰으로 갱신합니다.

## API 키로 연결

브라우저 로그인을 열 수 없는 클라이언트와 스크립트에는 키를 사용합니다. 관리자가 **설정 → API 키**에서 생성하며, 키는 자체 권한 범위를 가지고 한 회사에 속합니다. 키를 만들고 범위를 지정하는 방법은 [API 키](https://docs.alforse.com/ko/docs/building/api-keys.md)를 참조하십시오.

키를 `Authorization` 헤더로 보냅니다.

```http theme={null}
Authorization: Bearer alf_your_key_here
```

`alforse-key: alf_your_key_here` 헤더도 허용됩니다.

TIP

**명령이 준비되어 있습니다**

키를 만들면 대화 상자에 키 옆으로 **MCP 명령**(MCP Command)이 표시됩니다. 이를 복사하면 한 번에 Claude Code에 서버를 추가할 수 있습니다.

### 클라이언트 구성

**Claude Code**

```bash theme={null}
claude mcp add --transport http alforse \
  https://app.alforse.com/api/mcp \
  --header "Authorization: Bearer alf_your_key_here"
```

**Cursor** (프로젝트의 `.cursor/mcp.json`, 또는 기존 `mcpServers`에 병합)

```json theme={null}
{
  "mcpServers": {
    "alforse": {
      "url": "https://app.alforse.com/api/mcp",
      "headers": { "Authorization": "Bearer alf_your_key_here" }
    }
  }
}
```

**VS Code** (`.vscode/mcp.json`. VS Code가 키를 묻기 때문에 키가 파일에 저장되지 않습니다)

```json theme={null}
{
  "inputs": [
    { "id": "alforse-key", "type": "promptString", "description": "Alforse API key", "password": true }
  ],
  "servers": {
    "alforse": {
      "type": "http",
      "url": "https://app.alforse.com/api/mcp",
      "headers": { "Authorization": "Bearer ${input:alforse-key}" }
    }
  }
}
```

**그 밖의 클라이언트:** URL `https://app.alforse.com/api/mcp`와 `Authorization: Bearer …` 헤더를 제공합니다. URL 필드의 이름은 클라이언트마다 다르므로(예: `url` 또는 `serverUrl`) 클라이언트의 문서를 확인하십시오.

HEADS UP

**클라이언트당 키 하나**

어시스턴트나 스크립트마다 별도의 키를 사용하고, 필요한 범위만 부여하십시오(읽기 전용 어시스턴트라면 보기 범위만). 그러면 다른 키에 영향을 주지 않고 하나만 취소하거나 좁힐 수 있습니다.

## 어시스턴트가 보는 도구

작업마다 도구를 하나씩 두는 대신, 서버는 모든 작업에 접근하는 세 가지 도구를 제공합니다.

| 도구 | 기능 |
| - | - |
| `search_tools` | 키워드, 모듈 또는 위험 등급(`READ`, `WRITE`, `DESTRUCTIVE`)으로 사용 가능한 Alforse 작업을 검색합니다. 기본 20개, 최대 100개를 반환합니다. |
| `describe_tool` | 하나 이상의 작업에 대한 전체 계약을 반환합니다. 설명, 필요한 권한, 입력 및 응답 스키마가 포함됩니다. |
| `call_tool` | JSON 객체 형태의 인수로 작업을 실행합니다. |

작업은 계정, 회계, 문서, 재고, 청구, 품목, 인원, 생산, 구매, 품질, 자원, 판매, 설정, 공유, 사용자 영역에서 제공됩니다. Alforse가 명시적으로 게시한 작업만 사용할 수 있으며, 일부는 의도적으로 서버에서 제외되어 있습니다.

* 모든 호출은 앱과 동일한 권한 확인을 거치며, 쓰기는 동일한 서비스 계층에서 검증됩니다.
* 각 작업에는 위험 등급이 있어, 어시스턴트가 `WRITE` 또는 `DESTRUCTIVE` 작업을 실행하기 전에 사용자에게 확인할 수 있습니다.
* 목록 조회는 기본적으로 **25행**을 반환합니다. 어시스턴트는 `limit`(1–100)과 `offset`으로 페이지를 넘깁니다.
* 어시스턴트는 회사 시간대 기준의 오늘 날짜를 전달받으므로 "지난주" 같은 상대적 날짜가 올바르게 해석됩니다.

## 제한

| 제한 | 값 |
| - | - |
| 플랜 | Business. 그렇지 않으면 모든 호출이 `402`를 반환합니다. |
| 브라우저로 권한을 부여한 연결 | 사용자당 **분당 60건 요청**이며 모든 연결이 공유합니다 |
| API 키 | 키 자체의 제한이며 기본값은 분당 60건입니다([자세히](https://docs.alforse.com/ko/docs/building/api-keys.md#rate-limit)) |
| 액세스 토큰 수명 | 1시간이며 리프레시 토큰으로 자동 갱신됩니다 |
| 목록 조회당 행 수 | 기본 25개, 페이지당 최대 100개 |

제한에 도달하면 서버는 `429`와 함께 `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` 헤더로 응답합니다. `Retry-After`에 명시된 초만큼 기다린 다음 다시 시도하십시오.

## 문제 해결

| 증상 | 원인 | 해결 방법 |
| - | - | - |
| `402`와 "The MCP server is available on the Business plan. Upgrade to connect an agent to Alforse." (MCP 서버는 Business 플랜에서 사용할 수 있습니다. 에이전트를 Alforse에 연결하려면 업그레이드하세요.) | 회사가 Business 플랜이 아닙니다. | 플랜을 업그레이드하십시오([결제 및 구독](https://docs.alforse.com/ko/docs/reference/billing.md) 참조). 연결 자체는 변경할 필요가 없습니다. |
| 어시스턴트가 Alforse를 연 직후 "Access Denied" | 승인 페이지에 필요한 **설정**의 **업데이트** 권한이 없습니다. | 관리자에게 해당 권한을 요청하거나 API 키로 연결하십시오. |
| **권한 부여** 선택 시 "Invalid company"(`403`) | 선택한 회사의 구성원이 아닙니다. | 소속된 회사를 선택하십시오. |
| "Invalid redirect URI" 또는 "Invalid client" | 클라이언트가 등록하지 않은 반환 주소를 보냈거나 등록 정보를 알 수 없습니다. | 어시스턴트에서 서버를 제거한 뒤 다시 추가하여 새로 등록되게 하십시오. |
| "PKCE required for public clients" | 시크릿이 없는 클라이언트가 코드 챌린지를 보내지 않았습니다. | PKCE(`S256`)를 지원하는 클라이언트를 사용하십시오. |
| 이전에는 작동하다가 모든 호출에서 `401` | 액세스 토큰이 만료되어 갱신되지 않았거나, 더 이상 회사의 활성 구성원이 아니거나, API 키가 만료되었거나 삭제되었습니다. | 다시 연결(재승인)하거나 유효한 키를 사용하십시오. |
| `429` "Rate limit exceeded" | 분당 허용 요청 수를 초과했습니다. | `Retry-After`만큼 기다리십시오. 어시스턴트에게 더 적은 수의 큰 페이지로 가져오도록 요청하십시오. |
| `405` "Method not allowed. Use POST." | URL을 브라우저에서 열었거나 `GET`으로 호출했습니다. | 정상입니다. MCP 클라이언트는 `POST`를 사용합니다. 대신 어시스턴트에 URL을 추가하십시오. |
| 도구 호출이 권한 오류로 실패 | 연결된 사용자 또는 키의 범위가 해당 작업을 허용하지 않습니다. | Alforse에서 권한 또는 범위를 부여하십시오. 다음 호출부터 적용됩니다. |
| 어시스턴트가 작업을 찾지 못함 | MCP 서버에 게시되지 않았거나 검색어가 일치하지 않습니다. | 어시스턴트에게 모듈(예: "sales") 또는 필드 이름으로 검색하도록 요청하십시오. |

## 관련 문서

**API 키**

코딩 클라이언트, 스크립트, CI용 키를 만들고 범위를 지정합니다.

[Open](https://docs.alforse.com/ko/docs/building/api-keys.md)

**권한**

연결된 어시스턴트가 읽고 변경할 수 있는 항목입니다.

[Open](https://docs.alforse.com/ko/docs/reference/permissions.md)

**Slack의 어시스턴트**

Slack에서 Alforse를 사용합니다.

[Open](https://docs.alforse.com/ko/docs/integrations/assistant.md)

**결제 및 구독**

플랜과 업그레이드 방법입니다.

[Open](https://docs.alforse.com/ko/docs/reference/billing.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.