Agent Gateway API Reference

The Agent Gateway (L3) manages MCP (Model Context Protocol) servers, tool discovery and execution, A2A (Agent-to-Agent) communication, session lifecycle, security policies, human-in-the-loop (HITL) approvals, and MCP elicitation flows.

Base URL: http://localhost:5001

All endpoints require authentication via the Authorization header (Bearer JWT). Tenant identification is extracted from the JWT tenant_id claim or the x-tenant-id header.

Health

GET /

Service information, supported protocols, and endpoint discovery.

Response: 200 OK

json

{
  "service": "agent-gateway",
  "engine": "rust",
  "version": "0.1.0",
  "protocols": ["MCP", "A2A"],
  "endpoints": {
    "/v1/mcp/servers": "MCP server registry",
    "/v1/mcp/tools": "Tool discovery",
    "/v1/mcp/tools/call": "Execute a tool",
    "/v1/a2a/agents": "A2A agent registry",
    "/v1/a2a/send": "Send A2A message",
    "/v1/sessions": "Session management",
    "/v1/policies/:tenant_id": "Security policies",
    "/v1/hitl/pending": "HITL approval queue"
  }
}

curl Example:

bash

curl http://localhost:5001/

GET /health

Health check with MCP server count.

Response: 200 OK

json

{
  "status": "ok",
  "service": "agent-gateway",
  "engine": "rust",
  "mcp_servers": 3
}

curl Example:

bash

curl http://localhost:5001/health

MCP Servers

GET /v1/mcp/servers

List registered MCP servers, optionally filtered by tenant.

Headers:

Header	Required	Description
`Authorization`	Yes	`Bearer {jwt-token}`
`x-tenant-id`	No	Filter servers by tenant

Response: 200 OK

json

{
  "servers": [
    {
      "id": "srv-abc123",
      "name": "file-server",
      "url": "http://mcp-file-server:8080",
      "tenant_id": "tenant-alpha",
      "tools": [
        {"name": "read_file", "description": "Read file contents", "inputSchema": {}}
      ],
      "status": "active",
      "registered_at": "2026-03-25T10:00:00Z",
      "fingerprint": "sha256:abc123..."
    }
  ],
  "total": 1
}

curl Example:

bash

curl http://localhost:5001/v1/mcp/servers \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-tenant-id: tenant-alpha"

POST /v1/mcp/servers

Register a new MCP server. The gateway generates an ID if not provided, sets the status to active, and computes a tool fingerprint for poisoning detection.

Headers:

Header	Required	Description
`Authorization`	Yes	`Bearer {jwt-token}`
`Content-Type`	Yes	`application/json`

Request Body:

json

{
  "name": "file-server",
  "url": "http://mcp-file-server:8080",
  "tenant_id": "tenant-alpha",
  "tools": [
    {
      "name": "read_file",
      "description": "Read file contents",
      "inputSchema": {
        "type": "object",
        "properties": {
          "path": {"type": "string"}
        },
        "required": ["path"]
      }
    }
  ]
}

Response: 201 Created

json

{
  "id": "srv-abc123",
  "tools_registered": 1
}

Error Response: 409 Conflict (tool naming collision detected)

json

{
  "error": "tool_naming_collision",
  "collisions": ["read_file"]
}

WARNING

The gateway checks for tool naming collisions across all registered servers. If a tool name already exists on a different server, registration is rejected with 409 Conflict to prevent tool poisoning attacks.

curl Example:

bash

curl -X POST http://localhost:5001/v1/mcp/servers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "file-server",
    "url": "http://mcp-file-server:8080",
    "tenant_id": "tenant-alpha",
    "tools": [
      {"name": "read_file", "description": "Read file contents", "inputSchema": {"type": "object", "properties": {"path": {"type": "string"}}, "required": ["path"]}}
    ]
  }'

GET /v1/mcp/servers/:server_id

Get details for a specific MCP server.

Path Parameters:

Parameter	Description
`server_id`	MCP server identifier

Response: 200 OK

json

{
  "id": "srv-abc123",
  "name": "file-server",
  "url": "http://mcp-file-server:8080",
  "tenant_id": "tenant-alpha",
  "tools": [],
  "status": "active",
  "registered_at": "2026-03-25T10:00:00Z",
  "fingerprint": "sha256:abc123..."
}

Error Response: 404 Not Found

json

{"error": "Server not found"}

curl Example:

bash

curl http://localhost:5001/v1/mcp/servers/srv-abc123 \
  -H "Authorization: Bearer $TOKEN"

DELETE /v1/mcp/servers/:server_id

Remove an MCP server from the registry.

Path Parameters:

Parameter	Description
`server_id`	MCP server identifier

Response: 200 OK

json

{"removed": "srv-abc123"}

Error Response: 404 Not Found

json

{"error": "Server not found"}

curl Example:

bash

curl -X DELETE http://localhost:5001/v1/mcp/servers/srv-abc123 \
  -H "Authorization: Bearer $TOKEN"

GET /v1/mcp/servers/:server_id/tools

List tools registered on a specific MCP server.

Path Parameters:

Parameter	Description
`server_id`	MCP server identifier

Response: 200 OK

json

{
  "tools": [
    {"name": "read_file", "description": "Read file contents", "inputSchema": {}}
  ]
}

Error Response: 404 Not Found

json

{"error": "Server not found"}

curl Example:

bash

curl http://localhost:5001/v1/mcp/servers/srv-abc123/tools \
  -H "Authorization: Bearer $TOKEN"

MCP Tools

GET /v1/mcp/tools

Discover all tools across all MCP servers, optionally filtered by tenant.

Headers:

Header	Required	Description
`Authorization`	Yes	`Bearer {jwt-token}`
`x-tenant-id`	No	Filter tools by tenant

Response: 200 OK

json

{
  "tools": [
    {
      "tool": {"name": "read_file", "description": "Read file contents", "inputSchema": {}},
      "server_id": "srv-abc123",
      "server_name": "file-server"
    }
  ],
  "total": 1
}

curl Example:

bash

curl http://localhost:5001/v1/mcp/tools \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-tenant-id: tenant-alpha"

POST /v1/mcp/tools/call

Execute a tool on an MCP server. Validates arguments against the tool's JSON schema, enforces session constraints (tool allowlist, budget, HITL), and forwards the call via JSON-RPC 2.0.

Headers:

Header	Required	Description
`Authorization`	Yes	`Bearer {jwt-token}`
`Content-Type`	Yes	`application/json`

Request Body:

json

{
  "server_id": "srv-abc123",
  "tool_name": "read_file",
  "arguments": {"path": "/tmp/data.txt"},
  "tenant_id": "tenant-alpha",
  "session_id": "sess-xyz789"
}

Field	Type	Required	Description
`server_id`	string	Yes	Target MCP server ID
`tool_name`	string	Yes	Name of the tool to call
`arguments`	object	Yes	Tool arguments (validated against JSON schema)
`tenant_id`	string	Yes	Tenant identifier
`session_id`	string	No	Session ID for constraint enforcement

Response: 200 OK

json

{
  "result": {"content": "file contents here..."},
  "latency_ms": 42,
  "server_id": "srv-abc123",
  "tool_name": "read_file"
}

Error Responses:

Status	Type	Description
`202`	`pending_approval`	Tool call requires HITL approval (returns `approval_id`)
`400`	`validation_failed`	Argument validation failed against tool JSON schema
`403`	`tool_not_allowed`	Tool not in session allowlist
`404`	`server_not_found`	MCP server not found
`429`	`budget_exceeded`	Session token budget exceeded

HITL Pending Response: 202 Accepted

json

{
  "status": "pending_approval",
  "approval_id": "hitl-abc123",
  "message": "Tool call requires human approval"
}

curl Example:

bash

curl -X POST http://localhost:5001/v1/mcp/tools/call \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "srv-abc123",
    "tool_name": "read_file",
    "arguments": {"path": "/tmp/data.txt"},
    "tenant_id": "tenant-alpha",
    "session_id": "sess-xyz789"
  }'

:::note Every tool call is logged to the ClickHouse agent_audit_log table with hashed input/output values. Tool calls within a session update the session's tool call count. :::

A2A Agents

GET /v1/a2a/agents

List registered A2A agents.

Headers:

Header	Required	Description
`Authorization`	Yes	`Bearer {jwt-token}`

Response: 200 OK

json

{
  "agents": [],
  "total": 0,
  "note": "Register agents via POST /v1/a2a/agents"
}

curl Example:

bash

curl http://localhost:5001/v1/a2a/agents \
  -H "Authorization: Bearer $TOKEN"

POST /v1/a2a/agents

Headers:

Header	Required	Description
`Authorization`	Yes	`Bearer {jwt-token}`
`Content-Type`	Yes	`application/json`

Request Body:

json

{
  "id": "agent-summarizer",
  "name": "Document Summarizer",
  "url": "http://summarizer-agent:9000/a2a",
  "tenant_id": "tenant-alpha",
  "capabilities": ["summarize", "extract"],
  "description": "Summarizes documents and extracts key points"
}

Response: 201 Created

json

{
  "id": "agent-summarizer",
  "status": "registered"
}

curl Example:

bash

curl -X POST http://localhost:5001/v1/a2a/agents \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "agent-summarizer",
    "name": "Document Summarizer",
    "url": "http://summarizer-agent:9000/a2a",
    "tenant_id": "tenant-alpha",
    "capabilities": ["summarize", "extract"],
    "description": "Summarizes documents"
  }'

POST /v1/a2a/send

Send a message from one agent to another. Supports delegation chain tracking, loop detection, and chain depth limits.

Headers:

Header	Required	Description
`Authorization`	Yes	`Bearer {jwt-token}`
`Content-Type`	Yes	`application/json`

Request Body:

json

{
  "from_agent": "agent-orchestrator",
  "to_agent": "agent-summarizer",
  "message": {"task": "summarize", "document_id": "doc-123"},
  "tenant_id": "tenant-alpha",
  "session_id": "sess-xyz789",
  "delegation_chain": []
}

Field	Type	Required	Description
`from_agent`	string	Yes	Sending agent ID
`to_agent`	string	Yes	Target agent ID
`message`	object	Yes	Message payload
`tenant_id`	string	Yes	Tenant identifier
`session_id`	string	No	Session ID for context
`delegation_chain`	array	No	List of agents already in the chain (for loop detection)

Response (agent registered, forwarded successfully): 200 OK

json

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "from": "agent-orchestrator",
  "to": "agent-summarizer",
  "delegation_chain": ["agent-orchestrator"],
  "result": {"summary": "..."}
}

Response (agent not registered): 202 Accepted

json

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "from": "agent-orchestrator",
  "to": "agent-summarizer",
  "delegation_chain": ["agent-orchestrator"],
  "note": "Target agent not registered — task queued"
}

Error Responses:

Status	Type	Description
`400`	`chain_depth_exceeded`	Delegation chain depth exceeds max 5
`409`	`circular_delegation`	Target agent already in delegation chain (loop detected)
`502`	—	Target agent returned error or is unreachable

curl Example:

bash

curl -X POST http://localhost:5001/v1/a2a/send \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from_agent": "agent-orchestrator",
    "to_agent": "agent-summarizer",
    "message": {"task": "summarize", "document_id": "doc-123"},
    "tenant_id": "tenant-alpha",
    "delegation_chain": []
  }'

GET /v1/a2a/tasks/:task_id

Get the status of an A2A task.

Path Parameters:

Parameter	Description
`task_id`	Task identifier returned from `/v1/a2a/send`

Response: 200 OK

json

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "message": "Task status tracking via Redis (full implementation in progress)"
}

curl Example:

bash

curl http://localhost:5001/v1/a2a/tasks/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer $TOKEN"

Sessions

GET /v1/sessions

List sessions for a tenant.

Headers:

Header	Required	Description
`Authorization`	Yes	`Bearer {jwt-token}`
`x-tenant-id`	No	Tenant identifier (defaults to `"default"`)

Response: 200 OK

json

{
  "sessions": [
    {
      "id": "sess-xyz789",
      "tenant_id": "tenant-alpha",
      "agent_id": "agent-orchestrator",
      "tool_allowlist": ["read_file", "search"],
      "status": "active",
      "created_at": "2026-03-25T10:00:00Z"
    }
  ],
  "total": 1
}

curl Example:

bash

curl http://localhost:5001/v1/sessions \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-tenant-id: tenant-alpha"

POST /v1/sessions

Create a new agent session with explicit tool allowlist and budget.

Headers:

Header	Required	Description
`Authorization`	Yes	`Bearer {jwt-token}`
`Content-Type`	Yes	`application/json`

Request Body:

json

{
  "tenant_id": "tenant-alpha",
  "agent_id": "agent-orchestrator",
  "tool_allowlist": ["read_file", "search", "write_file"],
  "token_budget": 50000,
  "metadata": {"purpose": "document processing"}
}

Response: 201 Created

json

{
  "id": "sess-xyz789",
  "tenant_id": "tenant-alpha",
  "agent_id": "agent-orchestrator",
  "tool_allowlist": ["read_file", "search", "write_file"],
  "token_budget": 50000,
  "tokens_used": 0,
  "tool_calls": 0,
  "status": "active",
  "created_at": "2026-03-25T10:00:00Z"
}

curl Example:

bash

curl -X POST http://localhost:5001/v1/sessions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "tenant-alpha",
    "agent_id": "agent-orchestrator",
    "tool_allowlist": ["read_file", "search"],
    "token_budget": 50000
  }'

WARNING

Every agent session must have an explicit tool allowlist. The gateway denies by default — tools not in the allowlist are rejected with 403 Forbidden.

GET /v1/sessions/:session_id

Get session details.

Path Parameters:

Parameter	Description
`session_id`	Session identifier

Response: 200 OK

json

{
  "id": "sess-xyz789",
  "tenant_id": "tenant-alpha",
  "agent_id": "agent-orchestrator",
  "tool_allowlist": ["read_file", "search"],
  "token_budget": 50000,
  "tokens_used": 1200,
  "tool_calls": 5,
  "status": "active",
  "created_at": "2026-03-25T10:00:00Z"
}

Error Response: 404 Not Found

json

{"error": "Session not found"}

curl Example:

bash

curl http://localhost:5001/v1/sessions/sess-xyz789 \
  -H "Authorization: Bearer $TOKEN"

DELETE /v1/sessions/:session_id

Terminate a session. Logs a session_terminate audit entry.

Path Parameters:

Parameter	Description
`session_id`	Session identifier

Response: 200 OK

json

{
  "id": "sess-xyz789",
  "status": "terminated",
  "tenant_id": "tenant-alpha"
}

Error Response: 404 Not Found

json

{"error": "Session not found"}

curl Example:

bash

curl -X DELETE http://localhost:5001/v1/sessions/sess-xyz789 \
  -H "Authorization: Bearer $TOKEN"

GET /v1/sessions/:session_id/tools

List tools available to a session (filtered by the session's tool allowlist and tenant scope).

Path Parameters:

Parameter	Description
`session_id`	Session identifier

Response: 200 OK

json

{
  "tools": [
    {
      "tool": {"name": "read_file", "description": "Read file contents", "inputSchema": {}},
      "server_id": "srv-abc123",
      "server_name": "file-server"
    }
  ],
  "total": 1
}

Error Response: 404 Not Found

json

{"error": "Session not found"}

curl Example:

bash

curl http://localhost:5001/v1/sessions/sess-xyz789/tools \
  -H "Authorization: Bearer $TOKEN"

POST /v1/sessions/:session_id/execute

Execute a tool within a session context. Delegates to the tool call handler with the session ID automatically injected for constraint enforcement.

Path Parameters:

Parameter	Description
`session_id`	Session identifier

Request Body:

json

{
  "server_id": "srv-abc123",
  "tool_name": "read_file",
  "arguments": {"path": "/tmp/data.txt"},
  "tenant_id": "tenant-alpha"
}

Response: Same as POST /v1/mcp/tools/call.

curl Example:

bash

curl -X POST http://localhost:5001/v1/sessions/sess-xyz789/execute \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "srv-abc123",
    "tool_name": "read_file",
    "arguments": {"path": "/tmp/data.txt"},
    "tenant_id": "tenant-alpha"
  }'

Security / HITL

GET /v1/policies/:tenant_id

Get the security policy for a tenant.

Path Parameters:

Parameter	Description
`tenant_id`	Tenant identifier

Response: 200 OK

json

{
  "tenant_id": "tenant-alpha",
  "hitl_required_tools": ["delete_file", "execute_command"],
  "max_concurrent_sessions": 10,
  "max_tool_calls_per_session": 100,
  "allowed_network_hosts": ["api.example.com"],
  "updated_at": "2026-03-25T10:00:00Z"
}

curl Example:

bash

curl http://localhost:5001/v1/policies/tenant-alpha \
  -H "Authorization: Bearer $TOKEN"

PUT /v1/policies/:tenant_id

Set or update the security policy for a tenant.

Path Parameters:

Parameter	Description
`tenant_id`	Tenant identifier

Request Body:

json

{
  "hitl_required_tools": ["delete_file", "execute_command"],
  "max_concurrent_sessions": 10,
  "max_tool_calls_per_session": 100,
  "allowed_network_hosts": ["api.example.com"]
}

Response: 200 OK

json

{
  "tenant_id": "tenant-alpha",
  "hitl_required_tools": ["delete_file", "execute_command"],
  "max_concurrent_sessions": 10,
  "max_tool_calls_per_session": 100,
  "allowed_network_hosts": ["api.example.com"],
  "updated_at": "2026-03-25T12:00:00Z"
}

curl Example:

bash

curl -X PUT http://localhost:5001/v1/policies/tenant-alpha \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "hitl_required_tools": ["delete_file", "execute_command"],
    "max_concurrent_sessions": 10,
    "max_tool_calls_per_session": 100,
    "allowed_network_hosts": ["api.example.com"]
  }'

GET /v1/hitl/pending

List pending HITL (human-in-the-loop) approval requests for a tenant.

Headers:

Header	Required	Description
`Authorization`	Yes	`Bearer {jwt-token}`
`x-tenant-id`	No	Tenant identifier (defaults to `"default"`)

Response: 200 OK

json

{
  "pending": [
    {
      "id": "hitl-abc123",
      "session_id": "sess-xyz789",
      "tenant_id": "tenant-alpha",
      "tool_name": "delete_file",
      "arguments": {"path": "/data/important.txt"},
      "status": "pending",
      "request_type": "tool_call",
      "created_at": "2026-03-25T10:05:00Z"
    }
  ],
  "total": 1
}

curl Example:

bash

curl http://localhost:5001/v1/hitl/pending \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-tenant-id: tenant-alpha"

POST /v1/hitl/:approval_id/approve

Approve a pending HITL request.

Path Parameters:

Parameter	Description
`approval_id`	HITL approval request identifier

Response: 200 OK

json

{
  "id": "hitl-abc123",
  "status": "approved",
  "resolved_at": "2026-03-25T10:10:00Z"
}

Error Response: 404 Not Found

json

{"error": "Approval not found"}

curl Example:

bash

curl -X POST http://localhost:5001/v1/hitl/hitl-abc123/approve \
  -H "Authorization: Bearer $TOKEN"

POST /v1/hitl/:approval_id/deny

Deny a pending HITL request.

Path Parameters:

Parameter	Description
`approval_id`	HITL approval request identifier

Response: 200 OK

json

{
  "id": "hitl-abc123",
  "status": "denied",
  "resolved_at": "2026-03-25T10:10:00Z"
}

Error Response: 404 Not Found

json

{"error": "Approval not found"}

curl Example:

bash

curl -X POST http://localhost:5001/v1/hitl/hitl-abc123/deny \
  -H "Authorization: Bearer $TOKEN"

Elicitation

MCP elicitation enables mid-task structured input collection from humans. An agent can pause execution, request specific structured data (defined by a JSON schema), and resume once the user responds.

POST /v1/elicit

Create an elicitation request (pauses agent workflow, waits for user input).

Headers:

Header	Required	Description
`Authorization`	Yes	`Bearer {jwt-token}`
`Content-Type`	Yes	`application/json`

Request Body:

json

{
  "session_id": "sess-xyz789",
  "tenant_id": "tenant-alpha",
  "tool_name": "configure_deployment",
  "message": "Please confirm the deployment target environment.",
  "schema": {
    "type": "object",
    "properties": {
      "environment": {"type": "string", "enum": ["staging", "production"]},
      "confirm": {"type": "boolean"}
    },
    "required": ["environment", "confirm"]
  }
}

Field	Type	Required	Description
`session_id`	string	Yes	Session requesting elicitation
`tenant_id`	string	Yes	Tenant identifier
`tool_name`	string	Yes	Tool that triggered the elicitation
`message`	string	Yes	Human-readable prompt for the user
`schema`	object	Yes	JSON Schema defining expected response structure

Response: 202 Accepted

json

{
  "elicitation_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "type": "elicitation",
  "message": "Waiting for user input"
}

curl Example:

bash

curl -X POST http://localhost:5001/v1/elicit \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess-xyz789",
    "tenant_id": "tenant-alpha",
    "tool_name": "configure_deployment",
    "message": "Please confirm the deployment target.",
    "schema": {"type": "object", "properties": {"environment": {"type": "string"}}, "required": ["environment"]}
  }'

POST /v1/elicit/:elicit_id/respond

Respond to a pending elicitation with structured input.

Path Parameters:

Parameter	Description
`elicit_id`	Elicitation request identifier

Request Body: (must conform to the schema defined in the elicitation request)

json

{
  "environment": "staging",
  "confirm": true
}

Response: 200 OK

json

{
  "elicitation_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "responded",
  "response": {
    "environment": "staging",
    "confirm": true
  }
}

Error Response: 404 Not Found

json

{"error": "Elicitation not found"}

curl Example:

bash

curl -X POST http://localhost:5001/v1/elicit/550e8400-e29b-41d4-a716-446655440000/respond \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"environment": "staging", "confirm": true}'

Metrics

GET /metrics

Prometheus-format metrics endpoint.

Response: 200 OK (text/plain, Prometheus exposition format)

# HELP agent_gateway_tool_calls_total Total tool calls
# TYPE agent_gateway_tool_calls_total counter
agent_gateway_tool_calls_total 847
# HELP agent_gateway_tool_calls_denied Tool calls denied by policy
# TYPE agent_gateway_tool_calls_denied counter
agent_gateway_tool_calls_denied 12
# HELP agent_gateway_tool_latency_seconds Tool call latency
# TYPE agent_gateway_tool_latency_seconds histogram
agent_gateway_tool_latency_seconds_bucket{le="0.1"} 800
# HELP agent_gateway_sessions_total Sessions created
# TYPE agent_gateway_sessions_total counter
agent_gateway_sessions_total 156
# HELP agent_gateway_sessions_active Active sessions
# TYPE agent_gateway_sessions_active gauge
agent_gateway_sessions_active 23
# HELP agent_gateway_a2a_hops_total A2A message hops
# TYPE agent_gateway_a2a_hops_total counter
agent_gateway_a2a_hops_total 89
# HELP agent_gateway_hitl_requests_total HITL requests created
# TYPE agent_gateway_hitl_requests_total counter
agent_gateway_hitl_requests_total 34
# HELP agent_gateway_hitl_approved HITL requests approved
# TYPE agent_gateway_hitl_approved counter
agent_gateway_hitl_approved 28
# HELP agent_gateway_hitl_denied HITL requests denied
# TYPE agent_gateway_hitl_denied counter
agent_gateway_hitl_denied 6
# HELP agent_gateway_tool_poisoning_detected Tool poisoning attempts
# TYPE agent_gateway_tool_poisoning_detected counter
agent_gateway_tool_poisoning_detected 1

curl Example:

bash

curl http://localhost:5001/metrics

Endpoint Summary

Method	Path	Description
GET	`/`	Service info and endpoint discovery
GET	`/health`	Health check
GET	`/metrics`	Prometheus metrics
GET	`/v1/mcp/servers`	List MCP servers
POST	`/v1/mcp/servers`	Register MCP server
GET	`/v1/mcp/servers/:server_id`	Get MCP server details
DELETE	`/v1/mcp/servers/:server_id`	Remove MCP server
GET	`/v1/mcp/servers/:server_id/tools`	List server tools
GET	`/v1/mcp/tools`	Discover all tools
POST	`/v1/mcp/tools/call`	Execute a tool
GET	`/v1/a2a/agents`	List A2A agents
POST	`/v1/a2a/agents`	Register A2A agent
POST	`/v1/a2a/send`	Send A2A message
GET	`/v1/a2a/tasks/:task_id`	Get A2A task status
GET	`/v1/sessions`	List sessions
POST	`/v1/sessions`	Create session
GET	`/v1/sessions/:session_id`	Get session
DELETE	`/v1/sessions/:session_id`	Terminate session
GET	`/v1/sessions/:session_id/tools`	List session tools
POST	`/v1/sessions/:session_id/execute`	Execute tool in session
GET	`/v1/policies/:tenant_id`	Get security policy
PUT	`/v1/policies/:tenant_id`	Set security policy
GET	`/v1/hitl/pending`	List pending HITL requests
POST	`/v1/hitl/:approval_id/approve`	Approve HITL request
POST	`/v1/hitl/:approval_id/deny`	Deny HITL request
POST	`/v1/elicit`	Create elicitation request
POST	`/v1/elicit/:elicit_id/respond`	Respond to elicitation

Agent Gateway API Reference ​

Health ​

GET / ​

GET /health ​

MCP Servers ​

GET /v1/mcp/servers ​

POST /v1/mcp/servers ​

GET /v1/mcp/servers/:server_id ​

DELETE /v1/mcp/servers/:server_id ​

GET /v1/mcp/servers/:server_id/tools ​

MCP Tools ​

GET /v1/mcp/tools ​

POST /v1/mcp/tools/call ​

A2A Agents ​

GET /v1/a2a/agents ​

POST /v1/a2a/agents ​

POST /v1/a2a/send ​

GET /v1/a2a/tasks/:task_id ​

Sessions ​

GET /v1/sessions ​

POST /v1/sessions ​

GET /v1/sessions/:session_id ​

DELETE /v1/sessions/:session_id ​

GET /v1/sessions/:session_id/tools ​

POST /v1/sessions/:session_id/execute ​

Security / HITL ​

GET /v1/policies/:tenant_id ​

PUT /v1/policies/:tenant_id ​

GET /v1/hitl/pending ​

POST /v1/hitl/:approval_id/approve ​

POST /v1/hitl/:approval_id/deny ​

Elicitation ​

POST /v1/elicit ​

POST /v1/elicit/:elicit_id/respond ​

Metrics ​

GET /metrics ​

Endpoint Summary ​

Agent Gateway API Reference

Health

GET /

GET /health

MCP Servers

GET /v1/mcp/servers

POST /v1/mcp/servers

GET /v1/mcp/servers/:server_id

DELETE /v1/mcp/servers/:server_id

GET /v1/mcp/servers/:server_id/tools

MCP Tools

GET /v1/mcp/tools

POST /v1/mcp/tools/call

A2A Agents

GET /v1/a2a/agents

POST /v1/a2a/agents

POST /v1/a2a/send

GET /v1/a2a/tasks/:task_id

Sessions

GET /v1/sessions

POST /v1/sessions

GET /v1/sessions/:session_id

DELETE /v1/sessions/:session_id

GET /v1/sessions/:session_id/tools

POST /v1/sessions/:session_id/execute

Security / HITL

GET /v1/policies/:tenant_id

PUT /v1/policies/:tenant_id

GET /v1/hitl/pending

POST /v1/hitl/:approval_id/approve

POST /v1/hitl/:approval_id/deny

Elicitation

POST /v1/elicit

POST /v1/elicit/:elicit_id/respond

Metrics

GET /metrics

Endpoint Summary