Skip to main content

Call Tool

Execute an MCP tool through the Willow gateway using a simple HTTP POST request. This endpoint lets you invoke any tool without maintaining a persistent MCP connection — useful for scripts, CI/CD pipelines, backend services, and one-off automations.

Endpoint​

POST /call/:integrationSlug/:toolSlug
ParameterTypeLocationDescription
integrationSlugstringpathThe slug of the MCP server (integration) that owns the tool
toolSlugstringpathThe slug of the tool to call. May optionally be prefixed with integrationSlug__ (the prefix is stripped automatically)

Authentication​

The gateway uses Willow Connect credentials. Include your access key and token in the Authorization header, separated by a colon:

Authorization: <userAccessKey>:<token>

These credentials are issued through the OAuth authorization flow or via the Auth Exchange endpoint.

Request Body​

The request body contains the tool's input arguments as a JSON object. The shape depends on the tool being called.

{
  "query": "open issues assigned to me",
  "limit": 10
}

Response​

Success — 200 OK​

Returns the tool's output wrapped in a data field:

{
  "data": {
    "issues": [
      { "id": "ISS-42", "title": "Fix login bug", "status": "open" }
    ]
  }
}

The structure inside data depends on the tool's return type.

Error — 401 Unauthorized​

Returned when the access key or token is invalid, expired, or the user is not permitted to call the tool.

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "invalid-mcp-s-token"
}

Error — 404 Not Found​

Returned when the requested tool does not exist on the integration.

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Tool not found"
}

Examples​

cURL​

curl -X POST \
  "https://gateway.your-domain.com/call/linear/list-issues" \
  -H "Authorization: <accessKey>:<token>" \
  -H "Content-Type: application/json" \
  -d '{"query": "assigned to me", "limit": 5}'

Node.js​

const response = await fetch(
  "https://gateway.your-domain.com/call/linear/list-issues",
  {
    method: "POST",
    headers: {
      Authorization: `${accessKey}:${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ query: "assigned to me", limit: 5 }),
  },
);

const { data } = await response.json();

Python​

import requests

response = requests.post(
    "https://gateway.your-domain.com/call/linear/list-issues",
    headers={
        "Authorization": f"{access_key}:{token}",
        "Content-Type": "application/json",
    },
    json={"query": "assigned to me", "limit": 5},
)

data = response.json()["data"]

How It Works​

  1. The gateway validates the credentials against Willow's permission system.
  2. If the user is permitted to call the tool, the gateway executes it on the appropriate MCP server.
  3. The tool's MCP response content is converted to a plain JSON value and returned.
  4. All calls are recorded in the audit log with the tool name, arguments, user, and MCP client.

Notes​

  • The tool slug can be passed either as the bare name (list-issues) or prefixed with the integration slug (linear__list-issues). The prefix is stripped automatically.
  • If the user does not have permission to call the tool, the call is still logged as an audit event with a "Not Permitted" error before returning 401.
  • Rate limits and guardrails configured for the tool still apply through the gateway.
On this page