Tool Calls¶
POST /mcp/tools/call is the core proxy endpoint. Every agent tool call goes through here for governance evaluation.
Request¶
Request Body¶
{
"agent_id": "my-agent-v1",
"agent_type": "autonomous",
"agent_version": "1.0.0",
"tool": "http",
"method": "GET",
"params": {"url": "https://api.example.com/data"}
}
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
agent_id | string | Yes | 1-256 chars, ^[a-zA-Z0-9._-]+$ | Unique agent identifier |
agent_type | string | Yes | 1-128 chars | Agent category |
agent_version | string | Yes | Semver ^\d+\.\d+\.\d+.*$ | Agent version |
tool | string | Yes | 1-256 chars | Tool being called |
method | string | Yes | 1-256 chars | Operation on the tool |
params | object | Yes | Max 64KB | Tool call parameters |
Governance Pipeline¶
Each request passes through these layers:
- Rate limiting — per-tenant sliding window (Redis)
- Gateway constraints — hard safety blocks (blocked domains, daily caps, cooldowns)
- OPA Policy (Pass 1) — fast-path evaluation
- Behavioral enrichment — if needed, fetch agent history from Redis
- OPA Policy (Pass 2) — enriched evaluation with anomaly score
- Decision — allow, deny, or escalate
- Brokered execution — if credentials registered, execute on agent's behalf
- Audit logging — write to hash-chained audit trail
- Webhook dispatch — notify configured endpoints
Responses¶
Allowed (200)¶
With brokered execution:
{
"status": "allowed",
"action_id": "550e8400-...",
"execution_mode": "vargate_brokered",
"execution_result": {"status_code": 200, "body": "..."},
"latency": {
"opa_eval_ms": 12,
"hsm_fetch_ms": 5,
"execution_ms": 230,
"total_ms": 247
}
}
Denied (403)¶
{
"detail": {
"action_id": "550e8400-...",
"violations": ["high_value_transaction_unapproved"],
"severity": "high",
"alert_tier": "escalate"
}
}
Pending Approval (202)¶
{
"status": "pending_approval",
"action_id": "550e8400-...",
"message": "Action requires human approval. It has been queued for review."
}
Error Responses¶
| Code | Reason | Example |
|---|---|---|
401 | Missing or invalid API key | {"detail": "Invalid API key"} |
422 | Validation error | {"detail": [{"loc": ["body", "agent_id"], ...}]} |
429 | Rate limit exceeded | {"error": "rate_limit_exceeded"} |
502 | OPA unavailable | {"detail": "OPA unreachable: ..."} |
Failure modes
The 502 behavior is configurable per tenant. By default, OPA failure is fail-closed (deny all). You can configure fail-open or fail-to-queue via PATCH /dashboard/settings with failure_config.
Code Examples¶
import httpx
client = httpx.Client(
base_url="https://vargate.ai/api",
headers={"X-API-Key": "YOUR_API_KEY"},
timeout=30,
)
response = client.post("/mcp/tools/call", json={
"agent_id": "my-agent-v1",
"agent_type": "assistant",
"agent_version": "1.0.0",
"tool": "http",
"method": "GET",
"params": {"url": "https://api.example.com/data"},
})
if response.status_code == 200:
print("Allowed:", response.json()["action_id"])
elif response.status_code == 403:
print("Denied:", response.json()["detail"]["violations"])
elif response.status_code == 202:
print("Pending approval:", response.json()["action_id"])
const response = await fetch("https://vargate.ai/api/mcp/tools/call", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-Key": "YOUR_API_KEY",
},
body: JSON.stringify({
agent_id: "my-agent-v1",
agent_type: "assistant",
agent_version: "1.0.0",
tool: "http",
method: "GET",
params: { url: "https://api.example.com/data" },
}),
});
if (response.status === 200) {
const data = await response.json();
console.log("Allowed:", data.action_id);
} else if (response.status === 403) {
const { detail } = await response.json();
console.log("Denied:", detail.violations);
}