io.enterpriseai.resources.McpRuntimeClient
Source: sdks/java/enterprise-ai-java/src/main/java/io/enterpriseai/resources/McpRuntimeClient.java. Back to the Java 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
MCP Runtime: isolated MCP instances of the caller in a project, started on the ToolHive Kubernetes Operator with credentials of their own and destroyed after use (ADR-0167). Credentials are only openbao:// or env:// references.
Constructor McpRuntimeClient
McpRuntimeClient(Transport transport)
Creates the client on the shared transport; EnterpriseAIClient builds it and exposes it through the accessor of the same name.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
transport | Transport | yes | Transport shared by the sub-clients of one client. |
McpRuntimeClient.createInstance
JsonNode createInstance(String projectId, Object body)
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 |
|---|---|---|---|---|
projectId | String | yes | Identifier (UUID) or slug of the project. | |
body | Object | yes | Template, name, parameters, personal credential, agents, allowed tools and idle time. |
Returns: JsonNode. Decoded JSON answer of the operation "Start an MCP instance".
Raises: the typed errors of the transport (Errors).
McpRuntimeClient.destroyInstance
JsonNode destroyInstance(String projectId, String instanceId)
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 |
|---|---|---|---|---|
projectId | String | yes | Identifier (UUID) or slug of the project. | |
instanceId | String | yes | Identifier (UUID) of the instance. |
Returns: JsonNode. Decoded JSON answer of the operation "Destroy an MCP instance".
Raises: the typed errors of the transport (Errors).
McpRuntimeClient.instance
JsonNode instance(String projectId, String instanceId)
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 |
|---|---|---|---|---|
projectId | String | yes | Identifier (UUID) or slug of the project. | |
instanceId | String | yes | Identifier (UUID) of the instance. |
Returns: JsonNode. Decoded JSON answer of the operation "Get an MCP instance".
Raises: the typed errors of the transport (Errors).
McpRuntimeClient.instances
JsonNode instances(String projectId)
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 |
|---|---|---|---|---|
projectId | String | yes | Identifier (UUID) or slug of the project. |
Returns: JsonNode. Decoded JSON answer of the operation "List the MCP instances of a project".
Raises: the typed errors of the transport (Errors).
McpRuntimeClient.instances
JsonNode instances(String projectId, String status)
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 |
|---|---|---|---|---|
projectId | String | yes | Identifier (UUID) or slug of the project. | |
status | String | yes | Only the instances in this state: provisioning, ready, sleeping, failed, terminating or terminated. |
Returns: JsonNode. Decoded JSON answer of the operation "List the MCP instances of a project".
Raises: the typed errors of the transport (Errors).
McpRuntimeClient.jwks
JsonNode jwks()
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: JsonNode. Decoded JSON answer of the operation "Get the MCP runtime verification keys".
Raises: the typed errors of the transport (Errors).
McpRuntimeClient.putPolicy
JsonNode putPolicy(String projectId, Object body)
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 |
|---|---|---|---|---|
projectId | String | yes | Identifier (UUID) or slug of the project. | |
body | Object | yes | The complete policy; omitted fields take their default. |
Returns: JsonNode. Decoded JSON answer of the operation "Set the MCP runtime policy of a project".
Raises: the typed errors of the transport (Errors).
McpRuntimeClient.startInstance
JsonNode startInstance(String projectId, String instanceId)
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 |
|---|---|---|---|---|
projectId | String | yes | Identifier (UUID) or slug of the project. | |
instanceId | String | yes | Identifier (UUID) of the instance. |
Returns: JsonNode. Decoded JSON answer of the operation "Start a sleeping or failed instance".
Raises: the typed errors of the transport (Errors).
McpRuntimeClient.stopInstance
JsonNode stopInstance(String projectId, String instanceId)
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 |
|---|---|---|---|---|
projectId | String | yes | Identifier (UUID) or slug of the project. | |
instanceId | String | yes | Identifier (UUID) of the instance. |
Returns: JsonNode. Decoded JSON answer of the operation "Put an MCP instance to sleep".
Raises: the typed errors of the transport (Errors).