# MCP 서버

> Piqline의 MCP 서버, 도구, ask_<agent> 도구, 어노테이션.

Source: https://piqline.com/ko/docs/api/mcp

MCP 서버는 API와 같은 도구를 제공하며, 에이전트마다 도구 하나가 추가됩니다. 세션이 없는 "Streamable HTTP" 전송을 사용하므로 각 요청은 독립적입니다. 키는 API와 같이 `Authorization` 헤더로 보냅니다.

## 서버

| 서버 | URL | 내용 |
| --- | --- | --- |
| 모든 도구 | `https://piqline.com/api/mcp` | 키로 호출할 수 있는 모든 도구와 각 에이전트의 `ask_<agent>` |
| 에이전트 하나 | `https://piqline.com/api/mcp/{agent}` | 해당 에이전트의 도구와 그 에이전트의 `ask_<agent>` |

`{agent}`는 `piqline`, `requete`, `facebook`, `linkedin`, `upwork`, `onboarding` 중 하나입니다. 에이전트 하나만 노출하는 서버는 도구 수를 제한하는 클라이언트에 적합합니다.

`tools/list`에는 키로 호출할 수 있는 도구만 표시됩니다. 도구가 보이지 않으면 키에 없는 스코프가 필요하다는 뜻입니다. `ask_<agent>` 도구에는 `agents` 스코프가, `ask_onboarding`에는 소유자 또는 관리자 역할이 필요합니다.

## 클라이언트 연결하기

각 클라이언트의 복사용 블록은 공식 문서와 대조해 [클라이언트 연결](/ko/docs/api/clients)에 정리되어 있습니다. Claude, ChatGPT, Codex, Cursor, VS Code, Gemini CLI, Zed, Cline, Mistral Le Chat, Copilot Studio, n8n, LangChain, Vercel SDK, 그리고 모든 로컬 클라이언트를 위한 릴레이를 다룹니다. 예를 들어 Claude Code의 경우:

```bash
claude mcp add --transport http piqline https://piqline.com/api/mcp \
  --header "Authorization: Bearer $PIQLINE_API_KEY"
```

## ask_<agent> 도구

`ask_piqline`, `ask_requete`, `ask_facebook`, `ask_linkedin`, `ask_upwork`, `ask_onboarding`은 요청 전체를 해당 에이전트에 넘깁니다. [`POST /api/v1/agents/{agent}`](/ko/docs/api/agents)와 같은 방식입니다.

| 인자 | 역할 |
| --- | --- |
| `message` | 자연어로 작성한 요청(필수). |
| `history` | 이 에이전트와의 이전 대화를 오래된 순서로 담습니다. 객체 `{ "role": "user" or "assistant", "text": "…" }`. |

응답에는 에이전트의 텍스트가 담깁니다. 에이전트가 질문이나 확인이 필요한 작업 때문에 멈추면, 응답에 그 사실과 호출해야 할 도구의 이름이 표시됩니다.

## 어노테이션

각 도구는 `readOnlyHint`, `destructiveHint`, `openWorldHint`를 선언합니다. 클라이언트는 이를 사용해 쓰기, 삭제, 실시간 읽기를 하는 도구 앞에서 확인을 요청할 수 있습니다.

## 오류

실패한 도구는 `isError: true`와 읽을 수 있는 메시지로 응답합니다. 도구 이전 단계(키, 스코프, 한도)의 거부는 `application/problem+json` 형식의 HTTP `401`, `403`, `429` 응답이며, [오류](/ko/docs/api/errors)에 설명되어 있습니다. 두 경우 모두 설정 → API 및 MCP의 요청 기록에 나타납니다.

## 계정 로그인

ChatGPT는 OAuth 로그인 또는 인증 없음만 허용합니다. 현재는 공개 엔드포인트인 `https://piqline.com/api/open/mcp`에 연결합니다. Piqline 계정(OAuth)으로 로그인하는 기능은 준비 중입니다. [클라이언트 연결](/ko/docs/api/clients) 페이지의 다른 모든 클라이언트는 키를 사용할 수 있습니다.
