Skip to main content
Turn the running gateway into an OpenAI-compatible and MCP endpoint so SDK clients and MCP tools reach the same live agents as chat users. One process, one agent state, three protocols. This is different from praisonai serve openai, which runs a separate standalone OpenAI-only process.

​
Quick Start

1

Enable in gateway.yaml

Add the api block to your gateway config:
gateway:
  api:
    openai: true
    mcp: true
2

Start with CLI flags

Enable the same surfaces from the command line:
praisonai gateway start --config gateway.yaml --openai-api --mcp
3

Enable in Python

Pass constructor flags to the gateway:
from praisonai.gateway import WebSocketGateway

WebSocketGateway(config=cfg, openai_api=True, mcp=True).start()

​
How It Works

Each API request dispatches into the gateway’s own registered agents, sharing the same session store and admission gate as chat users.
StepWhat happens
Resolve agentThe model field selects a registered agent; falls back to the first agent
Reuse sessionEach caller gets a stable session keyed by OpenAI-Session / X-Session-Id header or bearer token
Admit turnThe turn passes through the same admission gate as chat users
RespondThe reply is returned in OpenAI or MCP shape

​
Endpoints Exposed

SurfaceMethod + PathNotes
OpenAI chatPOST /v1/chat/completionsSSE streaming supported (stream: true)
OpenAI responsesPOST /v1/responsesAccepts string or messages-style input
OpenAI modelsGET /v1/modelsLists gateway-registered agent IDs
MCP JSON-RPCPOST /mcpMethods: initialize, tools/list, tools/call
Call the OpenAI surface with any standard client: 
from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:8765/v1", api_key="gateway-token")
reply = client.chat.completions.create(
    model="assistant",
    messages=[{"role": "user", "content": "Hello"}],
)
print(reply.choices[0].message.content)

​
Configuration Options

The gateway.api block maps to the ApiConfig dataclass. Both surfaces are opt-in; when both are False (default), no extra routes are mounted.
OptionTypeDefaultDescription
openaiboolFalseServe /v1/chat/completions, /v1/responses, /v1/models backed by the gateway’s live agents and sessions.
mcpboolFalseServe an MCP JSON-RPC endpoint at /mcp exposing registered agents as callable tools.
ApiConfig also exposes an enabled property (true if either surface is on), plus to_dict() and from_dict().

Full API surface

​
How Auth Works

Every API route is protected by the same gateway.auth_token as /info and /metrics. The /info endpoint advertises which surfaces are enabled in its api field, so clients can introspect a running gateway before connecting.

​
When to Use vs praisonai serve openai

Use the gateway api: block when you want SDK clients and MCP tools to share live agents and sessions with chat users. Use praisonai serve openai when you want a standalone, lightweight OpenAI-only process with no gateway state. See OpenAI-Compatible Server.
NeedChoose
SDK clients share chat users’ live sessionsGateway api: block
Standalone OpenAI-only endpointpraisonai serve openai
Expose gateway agents as MCP toolsGateway api.mcp

​
Best Practices

Leave openai: false and mcp: false (the defaults) unless a client needs them. Disabled surfaces mount no routes and leave the gateway unchanged.
Every /v1/* and /mcp route uses the same gateway.auth_token. Set a strong token when binding to any non-loopback interface.
Pass an OpenAI-Session or X-Session-Id header to reuse one agent session across calls. Without it, stateless callers get a fresh session per request.
GET /info returns an api field listing enabled surfaces, so tooling can confirm what a gateway exposes before dispatching.

Gateway

Gateway architecture and YAML configuration

OpenAI-Compatible Server

Standalone OpenAI-only server process

MCP Integration

Model Context Protocol servers and clients

Gateway CLI

CLI commands for managing the gateway