MCP server

Connect any MCP agent, so asking for approval is a tool call: the endpoint, the four tools and what they answer.

Agents that speak the Model Context Protocol can ask through tools instead of HTTP calls. The server is one endpoint, /mcp, and takes an agent key.

Connect

With Claude Code:

claude mcp add --transport http variantgate https://api.variantgate.com/mcp \
  --header "Authorization: Bearer gl_YOUR_KEY"

Or in any client that reads an MCP configuration file:

{
  "mcpServers": {
    "variantgate": {
      "type": "http",
      "url": "https://api.variantgate.com/mcp",
      "headers": { "Authorization": "Bearer gl_YOUR_KEY" }
    }
  }
}

Each client has its own page with the exact setup, including how to keep the key out of the file: Integrations.

The tools

request_approval
Ask a person to approve an action. Takes agent, action and summary, and optionally details, amount with currency, ttl_seconds and wait_seconds.
check_approval
Read the answer for a request id, waiting up to 30 seconds for a person to decide; 30 unless wait_seconds says less. Act only when allowed is true, and only on approved_summary and approved_amount.
withdraw_request
Take back a request nobody has decided, when the plan changes.
report_outcome
After acting, say whether it succeeded or failed, with a short note for the record.

The tools take the same fields and follow the same rules as the HTTP requests; they call the same code.

There is no tool for reading an inbox or deciding, so an agent cannot approve its own request this way either.

What every answer says

Every answer starts with one line saying what the model may do now, then the request itself as JSON. The same request also comes back as structuredContent for clients that read it.

APPROVED by …
You may act now: do exactly what was approved, nothing more. Then call report_outcome.
APPROVED WITH CHANGES by …
Act only on the approved version, which the line quotes, never on the original wording or amount.
APPROVED, but … paused
A person paused this agent or the whole workspace. Do not act now; check again later.
WAITING for a person
Do not act yet. Call check_approval, or withdraw_request if it is no longer needed.
DENIED by …
Do not act, and tell the user it was denied. The person's note, if any, is in the line.
EXPIRED
Nobody answered in time. Do not act.
WITHDRAWN
Do not act.

On initialize, the server also sends instructions for the model: when to ask, to keep waiting rather than asking again, to act only on an explicit yes and only on the approved version, and to report the outcome. Most clients pass them on.

Calling it by hand

To see exactly what a client sends, call a tool with curl. The server keeps no session, so no initialize is needed first:

curl -X POST https://api.variantgate.com/mcp \
  -H "authorization: Bearer $VARIANTGATE_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "request_approval",
      "arguments": {
        "agent": "mail-bot",
        "action": "email.send",
        "summary": "Send the March invoice (€1,240.00) to billing@acme.example",
        "amount": "1240.00",
        "currency": "EUR"
      }
    }
  }'
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "WAITING for a person to decide. Do not act yet. Call check_approval with request_id \"0190d1c5-…\" to wait for the answer, or withdraw_request if it is no longer needed.\n\n{\"id\":\"0190d1c5-…\",\"status\":\"pending\",\"allowed\":false,…}"
    }],
    "structuredContent": { "id": "0190d1c5-…", "status": "pending", "allowed": false, … },
    "isError": false
  }
}

When something is wrong

HTTP 401
No key, a wrong key or a revoked one. A person's sign-in token gets 403: the server is for agents only.
HTTP 429
The key's 600 calls a minute are used up. Same as the HTTP API.
Tool result with isError
The call reached a tool but was refused: a missing field, an unknown request id, an outcome reported twice. The text says why.
-32600
The message is not one JSON-RPC 2.0 request.
-32601
An unknown method. The server knows initialize, ping, tools/list and tools/call.
-32602
Invalid params, such as an unknown tool name.

A notification, a message without an id, is accepted with HTTP 202 and no reply. All error codes of the HTTP API are on Limits and errors.

A skill for your agent

Tools say what an agent can do, not when to do it. The repository includes a skill, asking-for-approval, that teaches an agent when to ask, how to write a summary a person can decide on, and to act only on an explicit yes.

Over MCP the model chooses the action name itself. Keep asking the default, allow only exact names, and put the actions that matter behind code that names them; see naming agent actions.

Protocol details

The server speaks protocol versions 2025-11-25 and 2025-06-18 over plain HTTP POST, one JSON-RPC message per call. It answers initialize with the version the client asked for when it speaks it, and otherwise with the newest. It keeps no session, so it needs no reconnecting and works behind any load balancer. A waiting call is held open for at most 30 seconds, well inside the usual client limit of a minute.

The server is listed in the official MCP Registry as com.variantgate/approvals, so clients that browse the registry can find it. They still ask you for the agent key.