Public API · GPTs Action · MCP

AI ToolBox API 사용법

Prompt App과 Workflow를 외부 자동화, GPTs Action, MCP 래퍼 서버에서 실행하는 방법을 정리했습니다. 실제 API 키 발급은 로그인 후 API 키 메뉴에서 진행하고, 이 문서는 로그인 없이 볼 수 있습니다.

API 키 발급하기 GPTs Action 연결 MCP 래퍼 구성

AI ToolBox API는 무엇인가요?

AI ToolBox API는 사용자가 만든 Prompt App과 Workflow를 외부 서비스, GPTs Action, MCP 래퍼 서버에서 실행할 수 있게 하는 REST API입니다. API 키를 발급한 뒤 Bearer 인증, JSON Body, X-AITB-Request-Id 헤더로 프롬프트와 워크플로를 안전하게 호출합니다.

AI ToolBox API AI API 사용법 GPTs Action GPT Action OpenAPI MCP 연동 AI 워크플로 API AI 프롬프트 API 프롬프트 실행 API 워크플로 실행 API AI 자동화 API

API로 할 수 있는 일

AI ToolBox API는 사용자의 계정 권한과 공유 범위 안에서 Prompt App과 Workflow를 실행합니다. 실행 결과는 JSON 응답으로 반환되고, 필요하면 run_id로 다시 조회할 수 있습니다.

Prompt App 실행

프롬프트 변수에 inputs를 넣고 텍스트 또는 JSON 결과를 받습니다. 반복되는 분석 질문, 요약, 문서 초안 작성에 적합합니다.

Workflow 실행

여러 Prompt App과 어댑터를 연결한 분석 흐름을 실행합니다. 워크플로 결과는 단계 간 매핑 안정성을 위해 JSON으로 반환됩니다.

툴 검색과 자동 선택

directory API로 사용 가능한 프롬프트와 워크플로를 검색하고, 자연어 요청에 맞는 후보를 찾아 GPTs Action이나 MCP tool 선택에 활용합니다.

기본 설정

API 키는 계정별로 발급되며 원문 키는 생성 직후 한 번만 표시됩니다. 키는 OpenAPI 스펙이나 코드 저장소에 직접 넣지 말고 환경 변수나 각 플랫폼의 인증 설정에 보관하세요.

Base URL

https://aitoolbox.kr/api/v1

공통 헤더

Authorization: Bearer aitb_live_...
Content-Type: application/json
X-AITB-Request-Id: 8f2b0b67-1c39-4a1d-aaf6-2c3b9b8f4e10
POST 요청에는 고유한 X-AITB-Request-Id가 필요합니다. 같은 API 키로 이미 사용한 request id를 다시 보내면 중복 실행 방지를 위해 거절될 수 있습니다.

엔드포인트

아래 엔드포인트는 clean URL 기준입니다. 서버 rewrite를 통해 API 라우터로 전달됩니다.

Method Endpoint 용도 인증
GET https://aitoolbox.kr/api/v1/health API 상태 확인 인증 없음
GET https://aitoolbox.kr/api/v1/directory/tools 접근 가능한 Prompt App과 Workflow 검색 Bearer API Key
GET https://aitoolbox.kr/api/v1/directory/tools/{tool_id}?include_spec=1 툴 상세와 GPTs Action용 OpenAPI 스펙 조회 Bearer API Key
POST https://aitoolbox.kr/api/v1/directory/resolve 자연어 요청에 맞는 툴 후보 탐색 Bearer API Key + X-AITB-Request-Id
POST https://aitoolbox.kr/api/v1/prompts/{prompt_code}/run 프롬프트 앱 실행 Bearer API Key + X-AITB-Request-Id
POST https://aitoolbox.kr/api/v1/workflows/{workflow_code}/run 워크플로 실행 Bearer API Key + X-AITB-Request-Id
GET https://aitoolbox.kr/api/v1/runs/{run_id} 프롬프트 또는 워크플로 실행 결과 조회 Bearer API Key

REST API 호출 예시

프롬프트 실행은 response_format으로 text 또는 json을 선택할 수 있습니다. 워크플로 실행은 항상 JSON 결과를 반환합니다.

요청 Body

{
    "inputs": {
        "고객명": "홍길동",
        "요청내용": "사업계획서 초안에 들어갈 핵심 내용을 정리해 주세요."
    },
    "response_format": "json",
    "confirm_side_effects": false
}

cURL 실행

curl -X POST "https://aitoolbox.kr/api/v1/prompts/{prompt_code}/run" \
  -H "Authorization: Bearer aitb_live_..." \
  -H "Content-Type: application/json" \
  -H "X-AITB-Request-Id: 8f2b0b67-1c39-4a1d-aaf6-2c3b9b8f4e10" \
  -d '{
    "inputs": {
        "고객명": "홍길동",
        "요청내용": "사업계획서 초안에 들어갈 핵심 내용을 정리해 주세요."
    },
    "response_format": "json",
    "confirm_side_effects": false
}'

툴 디렉터리 검색

curl "https://aitoolbox.kr/api/v1/directory/tools?q=사업계획서&kind=workflow&limit=5" \
  -H "Authorization: Bearer aitb_live_..."

GPTs Action 스펙 조회

curl "https://aitoolbox.kr/api/v1/directory/tools/workflow.Wxxxxxxxxxxxx?include_spec=1" \
  -H "Authorization: Bearer aitb_live_..."

GPTs Action으로 연결하기

AI ToolBox는 Prompt App과 Workflow별 OpenAPI 3.1 스펙을 생성합니다. 이 스펙을 GPT Builder의 Actions에 붙여 넣으면 GPT가 AI ToolBox API를 도구처럼 호출할 수 있습니다.

설정 순서

  1. 로그인 후 API 키 메뉴에서 키를 발급합니다.
  2. 프롬프트 또는 워크플로 실행 화면에서 GPT Action 스펙을 복사합니다.
  3. 또는 /directory/tools/{tool_id}?include_spec=1로 openapi_spec을 조회합니다.
  4. GPT Builder의 Actions Schema에 OpenAPI 스펙을 붙여 넣습니다.
  5. Authentication은 API Key, Auth Type은 Bearer로 설정하고 키 원문만 입력합니다.
  6. Preview에서 필수 inputs를 넣고 실행 결과의 run_id와 output을 확인합니다.

주의할 점

  • API 키를 OpenAPI 스펙 안에 적지 마세요. GPT Action 인증 설정에만 입력합니다.
  • OpenAI 서버의 출구 IP가 고정되어 있지 않다면 IP 허용 목록은 호출을 막을 수 있습니다. 운영용 키는 별도로 만들고 만료일, 크레딧 한도, 권한 범위로 제한합니다.
  • 이메일, 웹훅, 외부 쓰기 작업이 포함된 Workflow는 confirm_side_effects: true가 필요합니다.
  • Prompt App은 text/json 출력 선택이 가능하고, Workflow는 JSON 출력으로 실행됩니다.

MCP 형태로 활용하기

AI ToolBox API 자체는 REST API입니다. MCP 클라이언트에서 사용하려면 별도의 MCP 서버를 만들고, MCP tool handler가 AI ToolBox REST API를 호출하도록 감싸는 구조가 가장 단순합니다.

권장 MCP tool 구성

  • aitb_search_tools: directory/tools로 Prompt App과 Workflow 검색
  • aitb_resolve_tool: directory/resolve로 자연어 요청에 맞는 후보 선택
  • aitb_run_prompt: prompts/{prompt_code}/run 호출
  • aitb_run_workflow: workflows/{workflow_code}/run 호출
  • aitb_get_run: runs/{run_id}로 실행 결과 조회

설계 원칙

  • AI ToolBox API 키는 MCP 서버의 환경 변수로 보관합니다.
  • MCP 클라이언트에는 API 키 원문을 노출하지 않습니다.
  • POST 호출마다 MCP 서버에서 새 request id를 생성합니다.
  • 외부 쓰기 작업이 가능한 Workflow는 사용자 확인을 받은 뒤 confirm_side_effects를 true로 보냅니다.

MCP wrapper 핵심 호출 예시

import { randomUUID } from "node:crypto";

const AITB_API_BASE = process.env.AITB_API_BASE ?? "https://aitoolbox.kr/api/v1";
const AITB_API_KEY = process.env.AITB_API_KEY;

async function aitb(path, { method = "GET", body } = {}) {
  const headers = { Authorization: `Bearer ${AITB_API_KEY}` };
  if (body) {
    headers["Content-Type"] = "application/json";
    headers["X-AITB-Request-Id"] = randomUUID();
  }

  const res = await fetch(`${AITB_API_BASE}${path}`, {
    method,
    headers,
    body: body ? JSON.stringify(body) : undefined,
  });
  return res.json();
}

// MCP tool handler examples
export async function aitb_search_tools({ query, kind = "workflow" }) {
  return aitb(`/directory/tools?q=${encodeURIComponent(query)}&kind=${kind}&limit=5`);
}

export async function aitb_run_workflow({ workflow_code, inputs, confirm_side_effects = false }) {
  return aitb(`/workflows/${workflow_code}/run`, {
    method: "POST",
    body: { inputs, response_format: "json", confirm_side_effects },
  });
}

웹훅과 자동화 서비스

Zapier, Make, n8n, 사내 배치 서버처럼 HTTP Request를 보낼 수 있는 도구에서는 AI ToolBox API를 바로 호출할 수 있습니다.

1. 트리거 선택

폼 제출, CRM 업데이트, 결제 완료, 새 문서 생성 같은 이벤트를 자동화 서비스의 트리거로 둡니다.

2. HTTP Request 설정

Method는 POST, URL은 프롬프트 또는 워크플로 실행 엔드포인트, Headers에는 Authorization, Content-Type, X-AITB-Request-Id를 넣습니다.

3. 결과 저장

응답의 output, run_id, viewer_url을 CRM, 문서, Slack, Notion 같은 후속 단계에 저장하거나 전달합니다.

보안과 운영 체크리스트

키 관리

  • 서비스별로 API 키를 분리하고 이름을 명확히 정합니다.
  • 월 크레딧 한도와 만료일을 설정해 과도한 사용을 제한합니다.
  • 키가 노출되면 즉시 폐기하고 새 키를 발급합니다.

요청 관리

  • 민감한 고객 정보는 익명화하거나 요약해 inputs에 넣습니다.
  • POST 요청마다 새 X-AITB-Request-Id를 보냅니다.
  • AI 결과물은 초안으로 사용하고 중요한 수치와 사실은 원천 자료로 확인합니다.

자주 묻는 질문

AI ToolBox API로 무엇을 실행할 수 있나요?

프롬프트 앱 실행, 워크플로 실행, 툴 디렉터리 검색, 자연어 기반 툴 후보 탐색, 실행 결과 조회를 할 수 있습니다.

GPTs Action에는 어떻게 연결하나요?

프롬프트 또는 워크플로 상세 화면에서 OpenAPI 스펙을 복사하거나 디렉터리 상세 조회에 include_spec=1을 붙여 스펙을 받은 뒤 GPT Builder의 Actions Schema에 붙여 넣고 Bearer API Key 인증을 설정합니다.

AI ToolBox API를 MCP로 바로 호출할 수 있나요?

AI ToolBox API는 REST API입니다. MCP 형태로 쓰려면 작은 MCP 래퍼 서버를 만들고, MCP tool handler 안에서 AI ToolBox REST API를 호출하도록 구성합니다.

POST 요청에 X-AITB-Request-Id가 필요한 이유는 무엇인가요?

프롬프트와 워크플로 중복 실행을 줄이기 위한 요청 식별자입니다. POST 요청마다 8-80자 범위의 고유 값을 보내야 합니다.