mcp_runtime.go (package eai)
Source: sdks/go/mcp_runtime.go. Back to the Go 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 McpRuntimeService
McpRuntimeService groups the endpoints of the 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).
McpRuntimeService.CreateInstance
CreateInstance(ctx context.Context, projectID string, body any, opts ...CallOption) (json.RawMessage, error)
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 |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
projectID | string | yes | Identifier (UUID) or slug of the project. | |
body | any | yes | Template, name, parameters, personal credential, agents, allowed tools and idle time. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Start an MCP instance". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
McpRuntimeService.DestroyInstance
DestroyInstance(ctx context.Context, projectID string, instanceID string, opts ...CallOption) (json.RawMessage, error)
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 |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
projectID | string | yes | Identifier (UUID) or slug of the project. | |
instanceID | string | yes | Identifier (UUID) of the instance. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Destroy an MCP instance". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
McpRuntimeService.Instance
Instance(ctx context.Context, projectID string, instanceID string, opts ...CallOption) (json.RawMessage, error)
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 |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
projectID | string | yes | Identifier (UUID) or slug of the project. | |
instanceID | string | yes | Identifier (UUID) of the instance. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Get an MCP instance". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
McpRuntimeService.Instances
Instances(ctx context.Context, projectID string, opts ...CallOption) (json.RawMessage, error)
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 |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
projectID | string | yes | Identifier (UUID) or slug of the project. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "List the MCP instances of a project". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
McpRuntimeService.Jwks
Jwks(ctx context.Context, opts ...CallOption) (json.RawMessage, error)
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).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Get the MCP runtime verification keys". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
McpRuntimeService.PutPolicy
PutPolicy(ctx context.Context, projectID string, body any, opts ...CallOption) (json.RawMessage, error)
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 |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
projectID | string | yes | Identifier (UUID) or slug of the project. | |
body | any | yes | The complete policy; omitted fields take their default. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Set the MCP runtime policy of a project". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
McpRuntimeService.StartInstance
StartInstance(ctx context.Context, projectID string, instanceID string, opts ...CallOption) (json.RawMessage, error)
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 |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
projectID | string | yes | Identifier (UUID) or slug of the project. | |
instanceID | string | yes | Identifier (UUID) of the instance. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Start a sleeping or failed instance". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
McpRuntimeService.StopInstance
StopInstance(ctx context.Context, projectID string, instanceID string, opts ...CallOption) (json.RawMessage, error)
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 |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
projectID | string | yes | Identifier (UUID) or slug of the project. | |
instanceID | string | yes | Identifier (UUID) of the instance. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Put an MCP instance to sleep". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).