Skip to content
Olivares AI docs

Update or explicitly enable a tested upstream (AAL3).

PUT
/v1/console/mcp-gateway/servers/{id}
 
curl --request PUT \
  --url https://example.com/v1/console/mcp-gateway/servers/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "server": { "allowed_tools": [ { "destructive": true, "name": "example", "required_scope": "example" } ], "args": [ "example" ], "command": "example", "credential_ref": "example", "egress_cidrs": [ "example" ], "egress_hosts": [ "example" ], "enabled": true, "env": { "additionalProperty": "example" }, "env_secret_refs": { "additionalProperty": "example" }, "name": "example", "pin": { "program": "example", "sha256": "example", "version": "example" }, "targets": [ { "target_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "target_kind": "workspace" } ], "transport": "stdio", "trust": { "issuer": "example", "jwks": {}, "jwks_url": "example", "resource": "example" }, "url": "https://example.com" }, "version": 1 }'

Updates an own-tenant server using version compare-and-swap. Enabling requires a successful current probe, resource and issuer trust and explicit tool scopes. Requires tenant admin and AAL3.

Authorizations

Section titled “ Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
id
required
string format: uuid

Server identifier in this tenant.

Header Parameters

Section titled “ Header Parameters ”
X-Olivares-Tenant
string format: uuid

Authenticated target tenant; workspace-confined credentials are refused.

Request Body required

Section titled “ Request Body required ”
Media type application/json
object
server
required
object
allowed_tools

Explicit administrator-authored tool authority. Enabling with this field omitted gives every tested tool tools:call scope and requires approval, regardless of server annotations. Only an explicit policy can allow a call without approval. An explicit empty array permits no tools.

Array<object>
object
destructive
required
boolean
name
required
string
required_scope
required
string
args

Existing script and file arguments receive exact read/execute grants without opening their parents. Existing named code directories are read-only. The session folder is the only writable user directory; the runner supplies a private home and temp. Engine protected files remain denied; managed code below data/tools is readable.

Array<string>
command

Executable on the engine node. No shell is used. Infer stdio when supplied; omit URL. Runs as the engine user in the session folder with the session runner; process confinement follows the runner’s reported state. Without egress_hosts the command keeps the network of its launch.

string
credential_ref

Own tenant store:mcp/ reference; empty means no upstream authentication. Never a value or global fallback.

string
egress_cidrs
Array<string>
egress_hosts

Command servers only: the HTTPS hosts (host or host:port, lowercase, port 443 implied) the command may reach, at public addresses only, through a per-launch network namespace and proxy. Any other host, localhost and loopback or private addresses are refused. A host that cannot build that boundary refuses the start. Changing the list withdraws the last test.

Array<string>
<= 16 items
enabled
boolean
env

Public environment values only; credentials belong in env_secret_refs. HOME, TMPDIR, TMP and TEMP are reserved: the runner supplies private child directories, removed at exit.

object
key
additional properties
string
env_secret_refs

Environment names mapped to own-tenant store:mcp/ references. Values resolve at launch and never enter arguments or logs.

object
key
additional properties
string
name
required
string
pin

Command servers only: run the tool installed with olivares tool install –from at this exact version. The engine sets command and sha256 from that verified install and refuses a version that is not installed. A launch whose executable digest differs refuses to start. A write that omits the field keeps the stored pin unless it changes command, which unpins the server; another digest withdraws the last test.

object
program
required
string
sha256

Filled by the engine from the verified install; a write that sends it must name that digest.

string
/^[0-9a-f]{64}$/
version
required
string
targets

Nodes of the skills assignment tree this server serves: a session gets its tools only when its run is under one of them (its workspace, registered folder, template, agent groups, agent or the session itself). Empty serves every session of the tenant. A write that omits the field keeps the stored targets; send [] to clear them. A target that does not exist matches no session.

Array<object>
<= 32 items
object
target_id
required
string format: uuid
target_kind
required
string
Allowed values: workspace folder template agent_group agent session
transport
string
Allowed values: stdio streamable_http
trust
object
issuer
required
string
jwks

Public asymmetric JWKS only; private keys are rejected.

object
jwks_url
string
resource
required
string
url

Exact HTTPS endpoint without credentials, query or fragment.

string format: uri
version
required

Current tenant configuration version; stale writes return 409.

integer

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

Current reference-only configuration

Media type application/json
object
governance
required
object
key
additional properties
string
read_only
required
boolean
servers
required
Array<object>
object
allowed_tools
required

Explicit administrator-authored tool authority. Enabling with this field omitted gives every tested tool tools:call scope and requires approval, regardless of server annotations. Only an explicit policy can allow a call without approval. An explicit empty array permits no tools.

Array<object>
object
destructive
required
boolean
name
required
string
required_scope
required
string
args

Existing script and file arguments receive exact read/execute grants without opening their parents. Existing named code directories are read-only. The session folder is the only writable user directory; the runner supplies a private home and temp. Engine protected files remain denied; managed code below data/tools is readable.

Array<string>
command

Executable on the engine node. No shell is used. Infer stdio when supplied; omit URL. Runs as the engine user in the session folder with the session runner; process confinement follows the runner’s reported state. Without egress_hosts the command keeps the network of its launch.

string
credential_ref

Own tenant store:mcp/ reference; empty means no upstream authentication. Never a value or global fallback.

string
egress_cidrs
required
Array<string>
egress_hosts

Command servers only: the HTTPS hosts (host or host:port, lowercase, port 443 implied) the command may reach, at public addresses only, through a per-launch network namespace and proxy. Any other host, localhost and loopback or private addresses are refused. A host that cannot build that boundary refuses the start. Changing the list withdraws the last test.

Array<string>
<= 16 items
enabled
required
boolean
env

Public environment values only; credentials belong in env_secret_refs. HOME, TMPDIR, TMP and TEMP are reserved: the runner supplies private child directories, removed at exit.

object
key
additional properties
string
env_secret_refs

Environment names mapped to own-tenant store:mcp/ references. Values resolve at launch and never enter arguments or logs.

object
key
additional properties
string
id
required
string
name
required
string
pin

Command servers only: run the tool installed with olivares tool install –from at this exact version. The engine sets command and sha256 from that verified install and refuses a version that is not installed. A launch whose executable digest differs refuses to start. A write that omits the field keeps the stored pin unless it changes command, which unpins the server; another digest withdraws the last test.

object
program
required
string
sha256

Filled by the engine from the verified install; a write that sends it must name that digest.

string
/^[0-9a-f]{64}$/
version
required
string
probe
required
object
detail

One redacted stderr line or OS error explaining a local server failure. Also present in the server’s stored status. Credentials and terminal control characters are removed.

string
<= 512 characters
http_status

The HTTP status the server answered, with reason http_status.

integer
>= 400 <= 599
reason

Why an unreachable test failed. Local servers report process_start or process_exit and a redacted one-line detail; remote failures report their connection class or HTTP status.

string
Allowed values: dns tls timeout connection_refused http_status process_start process_exit
state
required
string
tested_at
string
tools
required
Array<object>
object
fingerprint
required
string
name
required
string
read_only
boolean
proposed_allow
required

Registered tool names whose current successful catalogue declares read-only behavior. A proposal for administrator review, never authority: Test observes declarations without proving tool safety. Empty when no current proposal exists.

Array<string>
<= 128 items
targets

Nodes of the skills assignment tree this server serves: a session gets its tools only when its run is under one of them (its workspace, registered folder, template, agent groups, agent or the session itself). Empty serves every session of the tenant. A write that omits the field keeps the stored targets; send [] to clear them. A target that does not exist matches no session.

Array<object>
<= 32 items
object
target_id
required
string format: uuid
target_kind
required
string
Allowed values: workspace folder template agent_group agent session
transport
required
string
Allowed values: stdio streamable_http
trust
required
object
issuer
required
string
jwks

Public asymmetric JWKS only; private keys are rejected.

object
jwks_url
string
resource
required
string
url
required

Exact HTTPS endpoint without credentials, query or fragment.

string format: uri
session_endpoint
required

One /session/mcp endpoint aggregates the session’s enabled servers and Olivares work tools. It accepts the launch-issued session credential and calls internal module APIs with the resolved principal; it never forwards that bearer into the admin API. Server tool aliases are stable and server-scoped.

string
session_tools
required
boolean
source
required
string
Allowed values: file store
version
required

Current tenant configuration version; stale writes return 409.

integer
Example 
{
  "servers": [
    {
      "probe": {
        "reason": "dns"
      },
      "targets": [
        {
          "target_kind": "workspace"
        }
      ],
      "transport": "stdio"
    }
  ],
  "source": "file"
}

400

Section titled “ 400 ”

Admission, source ownership, version or availability refusal

Media type application/json
object
error
required
object
code
required
string
message
required
string
module

With code module_not_enabled: the namespace of the module this node does not run.

string
Example generated 
{
  "error": {
    "code": "example",
    "message": "example",
    "module": "example"
  }
}

401

Section titled “ 401 ”

Admission, source ownership, version or availability refusal

Media type application/json
object
error
required
object
code
required
string
message
required
string
module

With code module_not_enabled: the namespace of the module this node does not run.

string
Example generated 
{
  "error": {
    "code": "example",
    "message": "example",
    "module": "example"
  }
}

403

Section titled “ 403 ”

Admission, source ownership, version or availability refusal

Media type application/json
object
error
required
object
code
required
string
message
required
string
module

With code module_not_enabled: the namespace of the module this node does not run.

string
Example generated 
{
  "error": {
    "code": "example",
    "message": "example",
    "module": "example"
  }
}

404

Section titled “ 404 ”

Admission, source ownership, version or availability refusal

Media type application/json
object
error
required
object
code
required
string
message
required
string
module

With code module_not_enabled: the namespace of the module this node does not run.

string
Example generated 
{
  "error": {
    "code": "example",
    "message": "example",
    "module": "example"
  }
}

409

Section titled “ 409 ”

Admission, source ownership, version or availability refusal

Media type application/json
object
error
required
object
code
required
string
message
required
string
module

With code module_not_enabled: the namespace of the module this node does not run.

string
Example generated 
{
  "error": {
    "code": "example",
    "message": "example",
    "module": "example"
  }
}

503

Section titled “ 503 ”

Admission, source ownership, version or availability refusal

Media type application/json
object
error
required
object
code
required
string
message
required
string
module

With code module_not_enabled: the namespace of the module this node does not run.

string
Example generated 
{
  "error": {
    "code": "example",
    "message": "example",
    "module": "example"
  }
}