API Reference

This page covers the gateway management HTTP API — gateways, gateway lifecycle, MCP servers, MCP tools, and the MCP gateway proxy endpoint. Where a deployment exposes interactive docs, you can browse them at:

OpenAPI JSON: GET /openapi.json
Swagger UI: GET /docs
ReDoc: GET /redoc

Authentication

All endpoints accept either of:

JWT (Bearer): Authorization: Bearer <jwt>
API key: X-API-Key: <api_key> (format: sk-vai-...)

Gateways

`POST /api/gateways`

Create a new gateway. Returns 201 Created.

Request:

{
  "name": "Customer Support Gateway"
}

Response:

{
  "id": "gw_abc123",
  "name": "Customer Support Gateway",
  "created_by": "usr_xyz",
  "created_at": "2026-05-19T10:00:00Z",
  "updated_at": "2026-05-19T10:00:00Z",
  "action_guard_policy_id": null
}

`GET /api/gateways`

List all gateways accessible to the current user.

Response:

{
  "items": [
    {
      "id": "gw_abc123",
      "name": "Customer Support Gateway",
      "created_by": "usr_xyz",
      "created_at": "2026-05-19T10:00:00Z",
      "updated_at": "2026-05-19T10:00:00Z",
      "action_guard_policy_id": "agp_4d59ef9c..."
    }
  ]
}

`GET /api/gateways/{gateway_id}`

Get a specific gateway by ID.

`PATCH /api/gateways/{gateway_id}`

Update a gateway's name.

Request:

{
  "name": "Updated Gateway Name"
}

`DELETE /api/gateways/{gateway_id}`

Delete a gateway.

Response:

{ "message": "Gateway deleted successfully" }

Gateway Lifecycle

`POST /api/gateways/{gateway_id}/start`

Start the Gateway MCP server. Requires gateway:start permission.

Returns an error if the gateway is already running or starting.

Response:

{
  "status": "success",
  "message": "Gateway status updated to running",
  "port": null,
  "pid": null,
  "container_id": null,
  "mcp_url": null
}

`POST /api/gateways/{gateway_id}/stop`

Stop the Gateway MCP server. Requires gateway:stop permission.

Returns an error if the gateway is already stopped.

Response:

{ "message": "Gateway status updated to stopped" }

`GET /api/gateways/{gateway_id}/status`

Get the current MCP server status for a gateway.

Response:

{
  "gateway_id": "gw_abc123",
  "name": "Customer Support Gateway",
  "status": "running",
  "port": null,
  "pid": null,
  "container_id": null,
  "started_at": "2026-05-19T10:05:00Z",
  "mcp_url": "https://your-deployment/api/gateways/gw_abc123/mcp",
  "uptime_seconds": 300.0
}

Field	Description
`status`	`running` / `starting` / `stopped`
`mcp_url`	URL to use as the MCP endpoint in your AI client
`uptime_seconds`	Seconds since the gateway started (`null` if not running)

Gateway MCP Server Attachments

`POST /api/gateways/{gateway_id}/mcp-servers/{server_id}`

Attach a global MCP server to a gateway. Returns 201 Created.

Returns an error if the server is already attached.

Response:

{
  "gateway_id": "gw_abc123",
  "mcp_server_id": "mcp_def456",
  "message": "MCP server attached to gateway successfully"
}

`DELETE /api/gateways/{gateway_id}/mcp-servers/{server_id}`

Detach an MCP server from a gateway.

`GET /api/gateways/{gateway_id}/mcp-servers`

List all MCP servers attached to a gateway.

MCP Servers

MCP servers are registered globally and then attached to one or more gateways.

`POST /api/mcp-servers`

Request:

{
  "name": "Salesforce MCP",
  "transport": "sse",
  "connection_url": "https://mcp.salesforce.com/v1/sse",
  "command": null,
  "args": null,
  "env": null,
  "auth_type": "oauth",
  "identity_scheme": null
}

Field	Type	Required	Description
`name`	string	Yes	Display name for this server
`transport`	string	Yes	`http` / `sse` / `stdio`
`connection_url`	string	No	Remote server URL (for `http` / `sse` transports)
`command`	string	No	Executable to run (for `stdio` transport)
`args`	array	No	Arguments for the `stdio` command
`env`	object	No	Environment variables for the `stdio` process
`auth_type`	string	No	`oauth` or `none`
`identity_scheme`	string	No	Identity forwarding scheme

Response:

{
  "id": "mcp_def456",
  "name": "Salesforce MCP",
  "transport": "sse",
  "connection_url": "https://mcp.salesforce.com/v1/sse",
  "command": null,
  "args": null,
  "auth_type": "oauth",
  "identity_scheme": null,
  "registered_by": "usr_xyz",
  "created_at": "2026-05-19T10:00:00Z",
  "updated_at": "2026-05-19T10:00:00Z",
  "gateway_ids": []
}

`GET /api/mcp-servers`

List all global MCP servers, each with the gateway IDs they are attached to.

`GET /api/mcp-servers/{server_id}`

Get a specific MCP server with full details: attached gateways, discovered tools, and resources.

`PUT /api/mcp-servers/{server_id}`

Update an MCP server. All fields from the create request are accepted.

`DELETE /api/mcp-servers/{server_id}`

Delete an MCP server.

MCP Tools

`POST /api/mcp-servers/{server_id}/discover/tools`

Connect live to the upstream MCP server and refresh the tool list. Use this after adding or updating tools on the upstream server.

Response:

{
  "count": 3,
  "tools": [
    {
      "name": "create_lead",
      "description": "Create a new sales lead.",
      "inputSchema": { "type": "object", "properties": { "name": { "type": "string" } } }
    }
  ],
  "last_discovery_at": "2026-05-19T10:10:00Z"
}

`GET /api/mcp-servers/{server_id}/tools`

Return the cached tool list from the last discovery. Does not connect to the upstream server.

`POST /api/mcp-servers/{server_id}/tools/call`

Call a tool on the upstream MCP server directly.

Request:

{
  "name": "create_lead",
  "arguments": {
    "name": "John Doe",
    "email": "john@example.com"
  }
}

Response:

{
  "content": [
    { "type": "text", "text": "Lead created: id=lead_001" }
  ],
  "isError": false
}

MCP Resources

`POST /api/mcp-servers/{server_id}/discover/resources`

Connect live to the upstream MCP server and refresh the resource list. Use this after adding or updating resources on the upstream server.

Response:

{
  "count": 2,
  "resources": [
    {
      "uri": "file:///data/customers.csv",
      "name": "customers.csv",
      "description": "Customer records",
      "mimeType": "text/csv"
    }
  ],
  "last_discovery_at": "2026-05-19T10:10:00Z"
}

`GET /api/mcp-servers/{server_id}/resources`

Return the cached resource list from the last discovery, split into discovered and manually added resources. Does not connect to the upstream server.

Response:

{
  "total_count": 3,
  "discovered": {
    "resources": [
      { "uri": "file:///data/customers.csv", "name": "customers.csv", "mimeType": "text/csv" }
    ],
    "last_discovery_at": "2026-05-19T10:10:00Z"
  },
  "manual": {
    "resources": [
      { "uri": "file:///data/products.csv", "name": "products.csv" }
    ]
  }
}

`POST /api/mcp-servers/{server_id}/manual-resources`

Add a resource manually (without going through discovery).

Request:

{
  "name": "products.csv",
  "description": "Product catalog",
  "mimeType": "text/csv"
}

Field	Type	Required	Description
`name`	string	Yes	Resource name / URI identifier
`description`	string	No	Human-readable description
`mimeType`	string	No	MIME type of the resource

`DELETE /api/mcp-servers/{server_id}/manual-resources`

Delete a manually added resource by name.

Request:

{ "name": "products.csv" }

`POST /api/mcp-servers/{server_id}/resources/read`

Read a resource from the upstream MCP server by URI.

Request:

{ "uri": "file:///data/customers.csv" }

Response:

{
  "contents": [
    { "type": "text", "text": "id,name,email\n1,John Doe,john@example.com" }
  ]
}

MCP Gateway Proxy

The MCP Gateway proxy is the endpoint your AI clients connect to. It speaks the MCP JSON-RPC protocol and enforces all configured guardrails (Action Guard, access control) on every tool call.

`POST /api/gateways/{gateway_id}/mcp`

MCP JSON-RPC endpoint. Accepts Authorization: Bearer <token> (OAuth) or X-API-Key: <api_key>.

This is the URL you set as the MCP server address in your AI client. The gateway forwards the request to the appropriate upstream MCP server after authentication and policy evaluation.

`GET /api/gateways/{gateway_id}/mcp`

Readiness check — returns a message confirming the MCP server is ready.

OAuth 2.0 Discovery Endpoints

These endpoints are used automatically by MCP clients that support OAuth 2.0 dynamic client registration. No manual interaction is required.

Endpoint	Description
`GET /api/gateways/{gateway_id}/mcp/.well-known/openid-configuration`	OpenID Connect discovery document
`GET /api/gateways/{gateway_id}/mcp/.well-known/oauth-authorization-server`	OAuth 2.0 AS metadata (RFC 8414)
`GET /api/gateways/{gateway_id}/mcp/.well-known/oauth-protected-resource`	Protected resource metadata
`POST /api/gateways/{gateway_id}/mcp/register`	Dynamic client registration
`GET /api/gateways/{gateway_id}/mcp/authorize`	Authorization redirect
`POST /api/gateways/{gateway_id}/mcp/token`	Token exchange

Authentication​

Gateways​

POST /api/gateways​

GET /api/gateways​

GET /api/gateways/{gateway_id}​

PATCH /api/gateways/{gateway_id}​

DELETE /api/gateways/{gateway_id}​

Gateway Lifecycle​

POST /api/gateways/{gateway_id}/start​

POST /api/gateways/{gateway_id}/stop​

GET /api/gateways/{gateway_id}/status​

Gateway MCP Server Attachments​

POST /api/gateways/{gateway_id}/mcp-servers/{server_id}​

DELETE /api/gateways/{gateway_id}/mcp-servers/{server_id}​

GET /api/gateways/{gateway_id}/mcp-servers​

MCP Servers​

POST /api/mcp-servers​

GET /api/mcp-servers​

GET /api/mcp-servers/{server_id}​

PUT /api/mcp-servers/{server_id}​

DELETE /api/mcp-servers/{server_id}​

MCP Tools​

POST /api/mcp-servers/{server_id}/discover/tools​

GET /api/mcp-servers/{server_id}/tools​

POST /api/mcp-servers/{server_id}/tools/call​

MCP Resources​

POST /api/mcp-servers/{server_id}/discover/resources​

GET /api/mcp-servers/{server_id}/resources​

POST /api/mcp-servers/{server_id}/manual-resources​

DELETE /api/mcp-servers/{server_id}/manual-resources​

POST /api/mcp-servers/{server_id}/resources/read​

MCP Gateway Proxy​

POST /api/gateways/{gateway_id}/mcp​

GET /api/gateways/{gateway_id}/mcp​

OAuth 2.0 Discovery Endpoints​

Authentication

Gateways

`POST /api/gateways`

`GET /api/gateways`

`GET /api/gateways/{gateway_id}`

`PATCH /api/gateways/{gateway_id}`

`DELETE /api/gateways/{gateway_id}`

Gateway Lifecycle

`POST /api/gateways/{gateway_id}/start`

`POST /api/gateways/{gateway_id}/stop`

`GET /api/gateways/{gateway_id}/status`

Gateway MCP Server Attachments

`POST /api/gateways/{gateway_id}/mcp-servers/{server_id}`

`DELETE /api/gateways/{gateway_id}/mcp-servers/{server_id}`

`GET /api/gateways/{gateway_id}/mcp-servers`

MCP Servers

`POST /api/mcp-servers`

`GET /api/mcp-servers`

`GET /api/mcp-servers/{server_id}`

`PUT /api/mcp-servers/{server_id}`

`DELETE /api/mcp-servers/{server_id}`

MCP Tools

`POST /api/mcp-servers/{server_id}/discover/tools`

`GET /api/mcp-servers/{server_id}/tools`

`POST /api/mcp-servers/{server_id}/tools/call`

MCP Resources

`POST /api/mcp-servers/{server_id}/discover/resources`

`GET /api/mcp-servers/{server_id}/resources`

`POST /api/mcp-servers/{server_id}/manual-resources`

`DELETE /api/mcp-servers/{server_id}/manual-resources`

`POST /api/mcp-servers/{server_id}/resources/read`

MCP Gateway Proxy

`POST /api/gateways/{gateway_id}/mcp`

`GET /api/gateways/{gateway_id}/mcp`

OAuth 2.0 Discovery Endpoints