---
title: "Call MCP tools"
method: POST
path: "/mcp/tools/call"
tags: ["MCP"]
---

# Call MCP tools

`POST /mcp/tools/call`

Execute a batch of 1–5 MCP tool calls. Calls run concurrently and each result reports its own `status`. When Gumloop accepts the request, MCP execution failures such as target server authentication, policy blocks, invalid tools, upstream HTTP errors, and connection failures are returned in `results[*].status` and `results[*].error`. Top-level `4xx` responses are reserved for Gumloop request, authentication, and permission failures. `200` covers homogeneous execution outcomes (all calls succeeded or all calls failed); mixed success/failure batches return `207`. If you previously treated non-2xx HTTP statuses as MCP execution failures, update your integration to inspect each result's `status` and `error`.

## Request body

- object
  - `calls` object[], required — Tool calls to execute. Dispatched concurrently; the batch is capped at 5.
    - `ref` string, nullable — Caller-supplied identifier echoed back on the matching result. When omitted, Gumloop assigns the call's zero-based index in `calls` as its `ref`.
    - `server_id` string, required
    - `tool_name` string, required
    - `arguments` object — Arguments passed to the tool. Defaults to `{}`. Validated by the tool's `input_schema`.
  - `team_id` string, nullable — Team the calls are scoped to.

## Response `200`

Batch processed. Inspect each result's `status` and `error`; this can include all-success and all-failed execution outcomes.

- object
  - `results` object[]
    - `ref` string, required
    - `server_id` string, nullable
    - `tool_name` string, nullable
    - `status` string, required — One of `success`, `unauthenticated`, or `error`.
    - `content` object[], nullable — Raw MCP content blocks returned by the tool when `status` is `success`.
    - `error` object, nullable — Error payload when `status` is not `success`. Includes `code`, `message`, `type`, and optional `param` and `details`.

## Other responses

- `207` — Partial success — at least one call succeeded and at least one failed. Inspect each result's `status` and `error`.
- `400` — Invalid Gumloop request body, for example fewer than 1 or more than 5 calls.
- `401` — Unauthorized — missing or invalid Gumloop API credentials.
- `403` — Forbidden — the caller lacks permission to use this Gumloop API endpoint or requested team scope.
- `500` — Internal server error.

---

[API](https://skmtc.dev/gumloop/apis/public-api.md) · [All operations](https://skmtc.dev/gumloop/apis/public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/gumloop/public-api/revisions/115f2d6ce387/schema)