mcp

Extracts MCP JSON-RPC method, tool, resource, prompt, version, and session metadata into filter-visible request fields.

Praxis AI documentation version

On this page

Extracts MCP protocol metadata from JSON-RPC request bodies and promotes method, tool/resource/prompt name, JSON-RPC kind, protocol version, and session presence to request headers/filter results; stores session ID in durable metadata.

MCP static catalog filter that aggregates tool catalogs from multiple backend MCP servers and handles tools/list, tools/call, and current-profile broker methods (initialize, ping, and notifications/initialized).

Configuration Notes

Recognized methods include initialize, tools/call, tools/list, resources/read, resources/list, prompts/get, prompts/list, and ping.

Methods requiring a name selector (tools/call, resources/read, prompts/get) return a JSON-RPC error if the selector is missing and on_invalid is reject.

Writes mcp.* and json_rpc.* entries to the filter result set for branch chain conditions.

In the stateless profile, tools/call routes to the configured backend cluster by exposed tool name, stripping the public prefix from params.name and repairing the forwarded Mcp-Name header before forwarding.

In the current profile, tools/call returns -32601 because current-profile routing requires session infrastructure not implemented here.

Supports two protocol profiles: current (session-based, default) and stateless (MCP 2026-07-28, configurable). Version and cache fields are derived from the selected profile when omitted.

Configuration

Field	Type	Required	Description
`header_validation`	HeaderValidation	no	Header validation settings.
`header_validation.mismatch`	`reject` \| `ignore`	no	Behavior when header value conflicts with body-derived value.
`header_validation.missing`	`ignore` \| `synthesize` \| `reject`	no	Behavior when expected MCP headers are absent.
`headers`	McpHeaders	no	Header names for MCP metadata promotion. Must not be hop-by-hop, framing, Host, credential, API-key, or other internal `x-praxis-` names. Dedicated `x-praxis-mcp-` defaults remain allowed.
`headers.kind`	string	no	Header name for the JSON-RPC kind (e.g. `x-praxis-mcp-kind`).
`headers.method`	string	no	Header name for the MCP method (e.g. `x-praxis-mcp-method`).
`headers.name`	string	no	Header name for the tool/resource/prompt name (e.g. `x-praxis-mcp-name`).
`headers.protocol_version`	string	no	Header name for the MCP protocol version (e.g. `x-praxis-mcp-protocol-version`).
`headers.session_present`	string	no	Header name for MCP session presence (e.g. `x-praxis-mcp-session-present`).
`max_body_bytes`	integer	no	Maximum body size in bytes for `StreamBuffer`.
`on_invalid`	`continue` \| `reject` \| `error`	no	Invalid input handling behavior.
`cache_scope`	`public` \| `private`	no	Cache scope for stateless responses. Requires `protocol_profile: stateless`.
`cache_ttl_ms`	integer	no	Cache TTL in milliseconds for stateless responses. Requires `protocol_profile: stateless`.
`default_version`	string	no	Fallback MCP protocol version. When omitted, derived from the profile.
`invalid_tool_policy`	`reject_server` \| `filter_out`	no	Behavior when a tool has an invalid schema.
`path`	string	no	Public MCP path handled by Praxis.
`protocol_profile`	`current` \| `stateless`	no	Protocol profile governing session semantics and header requirements for this broker instance.
`servers`	McpServerConfig[]	no	Backend server definitions.
`servers[].name`	string	yes	Unique server name.
`servers[].cluster`	string	yes	Backend cluster name.
`servers[].path`	string	no	Backend MCP path.
`servers[].tool_prefix`	string	no	Tool prefix for this server.
`servers[].tools`	ToolConfig[]	no	Statically defined tools.
`servers[].tools[].name`	string	yes	Tool name on the backend.
`servers[].tools[].description`	string	no	Optional description.
`servers[].tools[].inputSchema`	any	no	Optional input schema. `schema` is accepted as a local shorthand.
`servers[].tools[].annotations`	any	no	Optional tool annotations.
`supported_versions`	string[]	no	Protocol versions accepted during negotiation. When omitted, derived from the profile.

Examples

Example 1

filter: mcp

Example 2

filter: mcp
max_body_bytes: 65536
on_invalid: reject
header_validation:
  mismatch: reject
  missing: ignore
headers:
  method: x-praxis-mcp-method
  name: x-praxis-mcp-name
  kind: x-praxis-mcp-kind
  protocol_version: x-praxis-mcp-protocol-version
  session_present: x-praxis-mcp-session-present

Example 3

filter: mcp
path: /mcp
max_body_bytes: 65536
servers:
  - name: weather
    cluster: weather-mcp
    path: /mcp
    tool_prefix: weather_
    tools:
      - name: get_weather
        description: Get current weather
  - name: calendar
    cluster: calendar-mcp
    path: /mcp
    tool_prefix: cal_
    tools:
      - name: create_event
        description: Create a calendar event

mcp