AxHub/Docs

클라이언트 연결

Claude Desktop · Cursor 에서 apphub-mcp 를 연결하고, tools/list · tools/call 을 바로 실행해 보세요.

시작하기 전에

  • MCP 서버: https://api.jocodingax.ai/mcp
  • 인증: Authorization: Bearer <access_token> (토큰 발급은 인증 & 권한 참고)
  • 프로토콜: JSON-RPC 2.0, 버전 2025-11-25
  • 세션: initialize 응답의 sessionId 를 Mcp-Session-Id 헤더로 그대로 돌려주세요

Claude Desktop 에 연결하기

mcp.json 에 서버 추가하기

Claude Desktop 설정 폴더 (~/Library/Application Support/Claude/) 안에 mcp.json 을 열고 서버를 등록해 주세요. 전송 방식이 HTTP + SSE 라서 "type": "sse" 로 적어 주세요.

mcp.json
{
  "mcpServers": {
    "apphub": {
      "type": "sse",
      "url": "https://api.jocodingax.ai/mcp",
      "authentication": {
        "type": "oauth",
        "resource_metadata": "https://api.jocodingax.ai/.well-known/oauth-protected-resource"
      }
    }
  }
}

Claude Desktop 이 resource_metadata URL 을 읽고, authorization server 를 찾고, OAuth 흐름으로 토큰을 알아서 받아와요.

Claude 재시작하고 확인하기

Claude Desktop 을 껐다 켜면 apphub 서버에 초록색 점이 뜨고, tools/list 로 26개 tool 을 쓸 수 있어요. App · Deploy · GitHub · Table · API 5개 카테고리로 묶여서 보여요.

Cursor 에 연결하기

Cursor 는 ~/.cursor/mcp.json 에 거의 같은 모양으로 넣어주면 돼요. 한 가지 차이는 전송 타입을 "type": "http" 로 적는다는 점이에요.

~/.cursor/mcp.json
{
  "mcpServers": {
    "apphub": {
      "type": "http",
      "url": "https://api.jocodingax.ai/mcp",
      "auth": {
        "strategy": "oauth_bearer",
        "resource_metadata": "https://api.jocodingax.ai/.well-known/oauth-protected-resource"
      }
    }
  }
}

curl 로 바로 써보고 싶어요

MCP 클라이언트 없이 바로 테스트해 보고 싶을 땐 curl 로 직접 호출할 수 있어요.

initialize — 세션 만들기

Terminal
$ curl -sS -X POST https://api.jocodingax.ai/mcp \
    -H "Authorization: Bearer $AX_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "jsonrpc":"2.0","id":1,"method":"initialize",
      "params":{"protocolVersion":"2025-11-25"}
    }'

응답 JSON 의 result.sessionId 를 Mcp-Session-Id 헤더 값으로 이어서 써 주세요.

tools/list — 어떤 tool 이 보여지는지

Terminal
$ curl -sS -X POST https://api.jocodingax.ai/mcp \
    -H "Authorization: Bearer $AX_ACCESS_TOKEN" \
    -H "Mcp-Session-Id: $SESSION_ID" \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

토큰의 scope 에 맞춰서 필터링된 tool 만 돌아와요. (예: read 만 있는 토큰엔 deploy_app 이 빠져요)

tools/call — 진짜로 한번 호출하기

Terminal
$ curl -sS -X POST https://api.jocodingax.ai/mcp \
    -H "Authorization: Bearer $AX_ACCESS_TOKEN" \
    -H "Mcp-Session-Id: $SESSION_ID" \
    -H "Content-Type: application/json" \
    -d '{
      "jsonrpc":"2.0","id":3,"method":"tools/call",
      "params":{
        "name":"deploy_app",
        "arguments":{"app_id":42,"strategy":"canary"}
      }
    }'

deploy_app 처럼 오래 걸리는 tool 은 arguments.task 를 넣어서 비동기로 돌릴 수 있어요:

비동기로 돌리기
{
  "name": "deploy_app",
  "arguments": {
    "app_id": 42,
    "task": { "ttl": 900, "pollInterval": 3 }
  }
}

그 뒤에는 tasks/result 나 tasks/get 으로 상태를 확인하거나, SSE 스트림으로 알림을 받을 수 있어요.

리소스 구독하기

앱이나 배포 상태가 바뀌는 걸 실시간으로 받고 싶으면 resources/subscribe 를 써 주세요.

resources/subscribe
{
  "jsonrpc":"2.0","id":10,"method":"resources/subscribe",
  "params":{ "uri": "apphub://apps/42/deployments" }
}

Mcp-Session-Id 헤더와 OAuth 토큰이 필요해요. 구독하고 나면 GET /mcp SSE 스트림으로 resources/updated 이벤트가 흘러와요.

다음으로 읽어보세요