JSON-RPC 호출 형식

ainote 의 모든 MCP 도구는 JSON-RPC 2.0 over HTTP POST.

Endpoint

POST https://api.ainote.dev/api/mcp
Content-Type: application/json
Authorization: McpKey <YOUR_KEY>

요청 형식

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "<도구 이름>",
    "arguments": { ... }
  }
}

필드	타입	설명
jsonrpc	string	항상 "2.0"
id	int / string	요청 식별자 (응답에 echo)
method	string	tools/list 또는 tools/call
params.name	string	도구 이름
params.arguments	object	도구별 파라미터

응답 형식 (성공)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "..."
      }
    ]
  }
}

또는 도구가 structured 반환:

{
  "result": {
    "content": [{ "type": "text", "text": "..." }],
    "structuredContent": {
      "task_id": 1234,
      "created_at": "2026-05-07T10:00:00Z"
    }
  }
}

응답 형식 (에러)

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params: title is required",
    "data": { "field": "title" }
  }
}

자세히: 에러 코드.

도구 목록 조회

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

응답:

{
  "result": {
    "tools": [
      {
        "name": "create_task",
        "description": "Create a new task with natural language parsing.",
        "inputSchema": { "type": "object", "properties": { ... } }
      },
      ...
    ]
  }
}

curl 예시

curl -X POST https://api.ainote.dev/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: McpKey YOUR_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_tasks",
      "arguments": { "due_today": true }
    }
  }'

shell 함수로 wrap: shell 함수.

Streaming (NDJSON)

대량 응답 시 Accept: application/x-ndjson 헤더 → 각 결과 한 줄씩:

curl -N -X POST https://api.ainote.dev/api/mcp \
  -H "Authorization: McpKey YOUR_KEY" \
  -H "Accept: application/x-ndjson" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_tasks","arguments":{"limit":1000}}}'

Batch 요청

여러 도구 한번에:

[
  { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "list_tasks", "arguments": {} } },
  { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "list_categories", "arguments": {} } }
]

응답도 배열 (순서 보장 X — id 로 매칭).

다음

• 인증 헤더
• 에러 코드
• 전체 도구 카탈로그