enterprise_ai.mcp

Source: sdks/python/src/enterprise_ai/mcp/__init__.py. Back to the Python SDK reference index.

note

This page is generated by tools/docs/gen_sdk_reference.py from the SDK sources and the OpenAPI text folders. Do not edit it by hand: change the source and regenerate.

Class McpError

A JSON-RPC error returned by an MCP server.

EaiError

Class McpClient

/v1/mcp.

Resource

McpClient.catalog

catalog(server: str | None = None) -> Any

Get the MCP tool catalogue. Catalogue: tools, input and output schemas, versions, scopes and approval status (approved, pending_approval, rejected), for the servers the request may see only, as GET /v1/mcp/servers.

Route: /v1/mcp/catalog (GET).

Name	Type	Default	Required	Description
server	str | None	None	no	Only the catalogue of this server (UUID or name).

Returns: Any. Decoded JSON answer of the operation "Get the MCP tool catalogue".

Raises: the typed errors of the transport (Errors).

McpClient.connect

connect(server_id: str, client_name: str = 'enterprise-ai-python', version: str = '1.0.0') -> Any

Call an MCP server through the gateway. JSON-RPC 2.0 proxy. The body is one request or a batch (at most 50 are handled). Needs tenant_admin, developer or agent and the ReBAC relation can_invoke. Refusals are answered as JSON-RPC errors with HTTP 200, and audited. Checks, in order: valid JSON-RPC 2.0; server active; project isolation (mcp_server_project_mismatch); allowed callers (mcp_principal_not_allowed); a sleeping hosted instance is woken up; a third party application must be active and granted the server; method allowed; for tools/call: tool in allowed_tools, scope tools:invoke, DLP on the arguments; policy mcp.call; quota reservation; for resources/read: URI in allowed_resources. Then the call is forwarded with the upstream credentials; tools/list and resources/list are filtered by the allow lists, tools/call results are masked by DLP and screened for prompt injection, and the call is metered as a tool usage.

Route: /v1/mcp/gateway/{server_id} (POST).

Name	Type	Default	Required	Description
server_id	str		yes	Identifier (UUID) or name of the MCP server.
client_name	str	'enterprise-ai-python'	no	Client name sent in clientInfo (default enterprise-ai-python).
version	str	'1.0.0'	no	Client version sent in clientInfo (default 1.0.0).

Returns: Any. Decoded JSON answer of the operation "Call an MCP server through the gateway".

Raises: the typed errors of the transport (Errors).

McpClient.delete_server

delete_server(server_id: str) -> Any

Delete an MCP server. Removes the server from the registry. Needs tenant_admin, the ReBAC relation owner and access to the project of the server. 404 mcp_server_not_found. Audited as mcp.server.delete.

Route: /v1/mcp/servers/{server_id} (DELETE).

Name	Type	Default	Required	Description
server_id	str		yes	Identifier (UUID) or name of the MCP server.

Returns: Any. Decoded JSON answer of the operation "Delete an MCP server".

Raises: the typed errors of the transport (Errors).

McpClient.discover

discover(server_id: str) -> Any

Discover the tools of an MCP server. MCP protocol discovery (initialize, tools/list): every new or changed tool schema becomes a catalogue version waiting for approval (mcp_tool_version, approvers tenant_admin or security_officer). Returns the versions created with their approval ids. Needs tenant_admin, developer or application_owner, the ReBAC relation editor and access to the project of the server.

Route: /v1/mcp/servers/{server_id}/discover (POST).

Name	Type	Default	Required	Description
server_id	str		yes	Identifier (UUID) or name of the MCP server.

Returns: Any. Decoded JSON answer of the operation "Discover the tools of an MCP server".

Raises: the typed errors of the transport (Errors).

McpClient.list_servers

list_servers(project: str | None = None, **page: Any) -> Any

List the MCP servers. Servers the request may see: project (id or slug) keeps the servers of that project; a request made in a project (X-Project header or an API key bound to a project) sees the servers of its project and those shared by the tenant, never those of another project (403 mcp_project_forbidden). Upstream secrets are never returned, only their references.

Route: /v1/mcp/servers (GET).

Name	Type	Default	Required	Description
project	str | None	None	no	Identifier (UUID) or slug of the project whose servers are listed.
**page	Any		no	Pagination options passed to the listing: limit (maximum number of items per page) and cursor (the next_cursor of the previous page). Iterating the returned page follows every cursor.

Returns: Any. Decoded JSON answer of the operation "List the MCP servers".

Raises: the typed errors of the transport (Errors).

McpClient.register_server

register_server(name: str, url: str, transport: str = 'streamable_http', **extra: Any) -> Any

Register an MCP server. Registers an upstream server (201). The URL must be http(s) on an internal host allowed by the MCP egress policy (403 mcp_online_forbidden otherwise); bearer, api_key and query_param need an openbao:// or env:// credential_ref, query_param needs param, connector needs connector (400 invalid_request). A name already used answers 409 conflict. The project (default X-Project) must be the request project (403 mcp_project_forbidden). Needs tenant_admin, developer or application_owner; the caller becomes ReBAC owner. Audited as mcp.server.create.

Route: /v1/mcp/servers (POST).

Name	Type	Default	Required	Description
name	str		yes	Name, unique in the tenant: lowercase letters, digits, ., _, -, 1 to 128 characters.
url	str		yes	HTTP(S) endpoint of the server on an internal host (8 to 2000 characters).
transport	str	'streamable_http'	no	streamable_http (default) or sse.
**extra	Any		no	Extra fields merged into the request body.

Returns: Any. Decoded JSON answer of the operation "Register an MCP server".

Raises: the typed errors of the transport (Errors).

McpClient.rpc

rpc(server_id: str, method: str, params: dict[str, Any] | None = None, request_id: int = 1) -> Any

Call an MCP server through the gateway. JSON-RPC 2.0 proxy. The body is one request or a batch (at most 50 are handled). Needs tenant_admin, developer or agent and the ReBAC relation can_invoke. Refusals are answered as JSON-RPC errors with HTTP 200, and audited. Checks, in order: valid JSON-RPC 2.0; server active; project isolation (mcp_server_project_mismatch); allowed callers (mcp_principal_not_allowed); a sleeping hosted instance is woken up; a third party application must be active and granted the server; method allowed; for tools/call: tool in allowed_tools, scope tools:invoke, DLP on the arguments; policy mcp.call; quota reservation; for resources/read: URI in allowed_resources. Then the call is forwarded with the upstream credentials; tools/list and resources/list are filtered by the allow lists, tools/call results are masked by DLP and screened for prompt injection, and the call is metered as a tool usage.

Route: /v1/mcp/gateway/{server_id} (POST).

Name	Type	Default	Required	Description
server_id	str		yes	Identifier (UUID) or name of the MCP server.
method	str		yes	JSON-RPC method of the MCP server, for example tools/list.
params	dict[str, Any] | None	None	no	Extra fields merged into the request.
request_id	int	1	no	JSON-RPC id of the request (default 1).

Returns: Any. Decoded JSON answer of the operation "Call an MCP server through the gateway".

Raises: the typed errors of the transport (Errors).

McpClient.server_tools

server_tools(server_id: str) -> Any

List the tools of an MCP server. Calls tools/list on the server through the gateway and returns the tools allowed by allowed_tools. Needs the ReBAC relation can_invoke and access to the project of the server. An upstream error answers 502 upstream_error.

Route: /v1/mcp/servers/{server_id}/tools (GET).

Name	Type	Default	Required	Description
server_id	str		yes	Identifier (UUID) or name of the MCP server.

Returns: Any. Decoded JSON answer of the operation "List the tools of an MCP server".

Raises: the typed errors of the transport (Errors).

McpClient.session

session(server_id: str) -> McpSession

A sync MCP session over the gateway.

Name	Type	Default	Required	Description
server_id	str		yes	Identifier of the registered MCP server.

Returns: McpSession. A McpSession: Typed helpers for the MCP methods the gateway proxies.

McpClient.set_access

set_access(server_id: str, principals: list[str]) -> Any

Set who may call an MCP server. MCP Gateway access control: which users and agents may call this server; an empty list lets every member of its project call it. Principal ids are letters, digits and :._@/- (up to 128 characters, 400 invalid_request). The access of a hosted instance is managed by the MCP runtime (409 mcp_instance_access_managed). Needs tenant_admin, developer or application_owner and access to the project of the server. Audited as mcp.server.access.

Route: /v1/mcp/servers/{server_id}/access (PUT).

Name	Type	Default	Required	Description
server_id	str		yes	Identifier (UUID) or name of the MCP server.
principals	list[str]		yes	Users and agents (principal ids, up to 200) allowed to call the server; empty: every member of its project.

Returns: Any. Decoded JSON answer of the operation "Set who may call an MCP server".

Raises: the typed errors of the transport (Errors).

McpClient.set_server_status

set_server_status(server_id: str, status: str, reason: str | None = None) -> Any

Enable or disable an MCP server. active goes through a promotion: an approval is opened and the answer is 202 with approval_id. disabled applies at once (every gateway call is then refused) and is audited as mcp.server.status. Needs tenant_admin or security_officer, the ReBAC relation editor and access to the project of the server.

Route: /v1/mcp/servers/{server_id}/status (POST).

Name	Type	Default	Required	Description
server_id	str		yes	Identifier (UUID) or name of the MCP server.
status	str		yes	active (through a promotion) or disabled (immediate).
reason	str | None	None	no	Why the status changes (up to 2000 characters).

Returns: Any. Decoded JSON answer of the operation "Enable or disable an MCP server".

Raises: the typed errors of the transport (Errors).

McpClient.sync_hosted

sync_hosted(project: str | None = None) -> Any

Publish the MCP servers hosted by the Navin Manager. Publishes the MCP servers hosted by the Navin Manager (service mcp-host) in their project: token kept in the Credential Broker, server of the project created or updated, servers no longer hosted disabled. project (id or slug, default the request project) limits the synchronisation to one project; a project other than the request one answers 403 mcp_project_forbidden. Needs tenant_admin and a tenant (403 tenant_required).

Route: /v1/mcp/hosted/sync (POST).

Name	Type	Default	Required	Description
project	str | None	None	no	Identifier (UUID) or slug of the only project to synchronise. Default: the project of the request.

Returns: Any. Decoded JSON answer of the operation "Publish the MCP servers hosted by the Navin Manager".

Raises: the typed errors of the transport (Errors).

Class McpSession

Typed helpers for the MCP methods the gateway proxies.

Attributes:

Name	Type	Required	Description
client		yes	The McpClient that sends the requests.
server_id		yes	Identifier of the MCP server of the session.
server_info	dict[str, Any]	yes	Answer of the last initialize, {} before.

Constructor McpSession

McpSession(client: McpClient, server_id: str) -> None

Session on one MCP server; request ids start at 1 and server_info stays empty until initialize.

Name	Type	Default	Required	Description
client	McpClient		yes	Parent client.
server_id	str		yes	Identifier of the registered MCP server.

McpSession.call_tool

call_tool(name: str, arguments: dict[str, Any] | None = None) -> dict[str, Any]

Call a tool of the server (tools/call).

Name	Type	Default	Required	Description
name	str		yes	Name of the tool, as given by list_tools.
arguments	dict[str, Any] | None	None	no	Arguments of the tool (default {}).

Returns: dict[str, Any]. The MCP result of the call (content, isError...), {} when empty.

McpSession.initialize

initialize(client_name: str = 'enterprise-ai-python', version: str = '1.0.0') -> dict[str, Any]

Send initialize with the protocol version 2025-06-18 and keep the answer in server_info.

Name	Type	Default	Required	Description
client_name	str	'enterprise-ai-python'	no	Client name sent in clientInfo (default enterprise-ai-python).
version	str	'1.0.0'	no	Client version sent in clientInfo (default 1.0.0).

Returns: dict[str, Any]. The server information (protocolVersion, capabilities, serverInfo).

McpSession.list_prompts

list_prompts() -> list[dict[str, Any]]

List the prompts of the server (prompts/list).

This element takes no parameter.

Returns: list[dict[str, Any]]. The prompts list of the answer, empty when absent.

McpSession.list_resources

list_resources() -> list[dict[str, Any]]

List the resources of the server (resources/list).

This element takes no parameter.

Returns: list[dict[str, Any]]. The resources list of the answer, empty when absent.

McpSession.list_tools

list_tools() -> list[dict[str, Any]]

List the tools of the server (tools/list).

This element takes no parameter.

Returns: list[dict[str, Any]]. The tools list of the answer, empty when absent.

McpSession.read_resource

read_resource(uri: str) -> dict[str, Any]

Read one resource of the server (resources/read).

Name	Type	Default	Required	Description
uri	str		yes	URI of the resource, as given by list_resources.

Returns: dict[str, Any]. The MCP result (contents), {} when empty.

McpSession.request

request(method: str, params: dict[str, Any] | None = None) -> Any

Send method and return its result.

Name	Type	Default	Required	Description
method	str		yes	JSON-RPC method of the MCP server.
params	dict[str, Any] | None	None	no	Extra fields merged into the request.

Returns: Any. The result of the JSON-RPC answer; an error answer raises McpError.

Functions

unwrap

unwrap(response: Any) -> Any

Return result of a JSON-RPC response or raise :class:McpError.

Name	Type	Default	Required	Description
response	Any		yes	JSON-RPC 2.0 answer of the gateway.

Returns: Any. The result field, or the answer itself when it is not a dict.

Raises: McpError.