enterprise_ai.mcp_runtime
Source: sdks/python/src/enterprise_ai/mcp_runtime/__init__.py. Back to the Python SDK reference index.
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 McpRuntimeClient
/v1/projects/{project_id}/mcp/instances, /v1/projects/{project_id}/mcp/policy, /v1/mcp/runtime/jwks.
Resource
McpRuntimeClient.create_instance
create_instance(project_id: str, template: str, params: dict[str, Any] | None = None, name: str | None = None, credential_ref: str | None = None, agents: list[str] | None = None, allowed_tools: list[str] | None = None, idle_timeout_seconds: int | None = None) -> Any
Start an MCP instance. Starts an isolated MCP instance of the caller in the project (202): ToolHive MCPServer of its own, credentials of its own, ready when ToolHive reports it Ready (GET the instance to follow it). Needs tenant_admin, developer or application_owner and the ReBAC relation editor on the project. Checks: the MCP Runtime is enabled (409 mcp_runtime_disabled); the template, its hosts and database roles are allowed by the project policy (403 mcp_template_not_allowed, mcp_host_not_allowed, mcp_database_role_not_allowed); a template with personal credentials needs credential_ref (422 mcp_credential_required); agents, tools and name are valid (422); quotas per user and per project (409 mcp_instance_quota); no other instance of the caller with the same name (409 mcp_instance_exists). A failed provisioning destroys the instance and returns the error. Audited as mcp.instance.create.
Route: /v1/projects/{project_id}/mcp/instances (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
project_id | str | yes | Identifier (UUID) or slug of the project. | |
template | str | yes | Template of the catalogue: lowercase letters, digits and -, 1 to 63 characters. | |
params | dict[str, Any] | None | None | no | Parameters declared by the template (string, integer or list of strings), checked against it and the project policy. |
name | str | None | None | no | Name of the instance, unique for the caller in the project (same pattern). Default: the template name. |
credential_ref | str | None | None | no | Personal secret of the user, openbao://... or env://... (template with credentials secret_ref). |
agents | list[str] | None | None | no | Agents (principal ids, up to 20) allowed to call the instance with its owner. |
allowed_tools | list[str] | None | None | no | Tools of the instance that may be called (up to 100). Default ["*"]. |
idle_timeout_seconds | int | None | None | no | Idle time before the instance sleeps, in seconds (60 to 86400), never above the project policy. Default: the project policy. |
Returns: Any. Decoded JSON answer of the operation "Start an MCP instance".
Raises: the typed errors of the transport (Errors).
McpRuntimeClient.destroy_instance
destroy_instance(project_id: str, instance_id: str) -> Any
Destroy an MCP instance. Destroys the instance at the end of the task: credentials revoked, resources deleted, gateway entry disabled, journal kept. Allowed for its owner, or tenant_admin and security_officer (recorded as an administrator destruction). Needs the ReBAC relation viewer on the project. Returns the instance and its journal. 404 mcp_instance_not_found.
Route: /v1/projects/{project_id}/mcp/instances/{instance_id} (DELETE).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
project_id | str | yes | Identifier (UUID) or slug of the project. | |
instance_id | str | yes | Identifier (UUID) of the instance. |
Returns: Any. Decoded JSON answer of the operation "Destroy an MCP instance".
Raises: the typed errors of the transport (Errors).
McpRuntimeClient.instance
instance(project_id: str, instance_id: str) -> Any
Get an MCP instance. The instance (its state read again from ToolHive while it is provisioning or ready) and its lifecycle journal in events. credential_active tells whether credentials are currently issued. Visible to its owner, tenant_admin and security_officer; needs the ReBAC relation viewer on the project. 404 mcp_instance_not_found.
Route: /v1/projects/{project_id}/mcp/instances/{instance_id} (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
project_id | str | yes | Identifier (UUID) or slug of the project. | |
instance_id | str | yes | Identifier (UUID) of the instance. |
Returns: Any. Decoded JSON answer of the operation "Get an MCP instance".
Raises: the typed errors of the transport (Errors).
McpRuntimeClient.instances
instances(project_id: str, status: str | None = None) -> Any
List the MCP instances of a project. Returns enabled (whether the MCP Runtime runs on this platform), the project policy (defaults when not configured), the catalogue state, the templates and the instances, newest first, at most 500: its own for a user, every one for tenant_admin and security_officer. Needs the ReBAC relation viewer on the project.
Route: /v1/projects/{project_id}/mcp/instances (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
project_id | str | yes | Identifier (UUID) or slug of the project. | |
status | str | None | None | no | Only the instances in this state: provisioning, ready, sleeping, failed, terminating or terminated. |
Returns: Any. Decoded JSON answer of the operation "List the MCP instances of a project".
Raises: the typed errors of the transport (Errors).
McpRuntimeClient.jwks
jwks() -> Any
Get the MCP runtime verification keys. Public verification keys of the tokens the MCP Gateway gives the ToolHive proxies (no secret: public keys only, as any OIDC JWKS). Read without authentication by the MCPOIDCConfig eai-mcp-runtime of every project namespace. 503 context_authority_unavailable when the key registry cannot be read.
Route: /v1/mcp/runtime/jwks (GET).
This element takes no parameter.
Returns: Any. Decoded JSON answer of the operation "Get the MCP runtime verification keys".
Raises: the typed errors of the transport (Errors).
McpRuntimeClient.put_policy
put_policy(project_id: str, allowed_templates: list[str] | None = None, allowed_hosts: list[str] | None = None, allowed_database_roles: list[str] | None = None, idle_timeout_seconds: int = 900, max_lifetime_seconds: int = 28800, max_instances_per_user: int = 3, max_instances_per_project: int = 20) -> Any
Set the MCP runtime policy of a project. Replaces the policy of the MCP Runtime of the project: templates, hosts, database roles, idle time, lifetime and quotas. Unknown templates, invalid host patterns or role names answer 422 mcp_policy_invalid. New and woken instances follow it. Needs tenant_admin and the ReBAC relation editor on the project. Audited as mcp.runtime.policy.
Route: /v1/projects/{project_id}/mcp/policy (PUT).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
project_id | str | yes | Identifier (UUID) or slug of the project. | |
allowed_templates | list[str] | None | None | no | Templates users may start (up to 100). Empty (default): every template of the catalogue. |
allowed_hosts | list[str] | None | None | no | Hosts the instances may reach, exact names or *.domain patterns (up to 200). Empty (default): no host, so a template that needs a host cannot start. |
allowed_database_roles | list[str] | None | None | no | Database roles a template may use (up to 100). Empty (default): none. |
idle_timeout_seconds | int | 900 | no | Maximum idle time before an instance sleeps, in seconds (60 to 86400, default 900). |
max_lifetime_seconds | int | 28800 | no | Maximum lifetime of a running generation, in seconds (300 to 86400, default 28800). |
max_instances_per_user | int | 3 | no | Running instances per user (1 to 20, default 3); sleeping and failed ones are not counted. |
max_instances_per_project | int | 20 | no | Running instances per project (1 to 200, default 20). |
Returns: Any. Decoded JSON answer of the operation "Set the MCP runtime policy of a project".
Raises: the typed errors of the transport (Errors).
McpRuntimeClient.start_instance
start_instance(project_id: str, instance_id: str) -> Any
Start a sleeping or failed instance. Starts a sleeping or failed instance again now (failure count reset): template and project policy checked again, new generation and credentials; ready when ToolHive reports it Ready (GET the instance to follow it). 409 mcp_instance_busy while another lifecycle operation runs. Allowed for its owner, tenant_admin and security_officer; needs the ReBAC relation viewer on the project. Returns the instance and its journal (202).
Route: /v1/projects/{project_id}/mcp/instances/{instance_id}/start (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
project_id | str | yes | Identifier (UUID) or slug of the project. | |
instance_id | str | yes | Identifier (UUID) of the instance. |
Returns: Any. Decoded JSON answer of the operation "Start a sleeping or failed instance".
Raises: the typed errors of the transport (Errors).
McpRuntimeClient.stop_instance
stop_instance(project_id: str, instance_id: str) -> Any
Put an MCP instance to sleep. Stops the instance now (credentials revoked, resources deleted): it sleeps, its gateway entry stays and its next call recreates it. Allowed for its owner, tenant_admin and security_officer; needs the ReBAC relation viewer on the project. Returns the instance and its journal.
Route: /v1/projects/{project_id}/mcp/instances/{instance_id}/stop (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
project_id | str | yes | Identifier (UUID) or slug of the project. | |
instance_id | str | yes | Identifier (UUID) of the instance. |
Returns: Any. Decoded JSON answer of the operation "Put an MCP instance to sleep".
Raises: the typed errors of the transport (Errors).