Test the connection and list its tools again

POST

/org/mcp-servers/{serverId}/test

const url = 'https://api.asklucy.eu/v1/org/mcp-servers/mcp_8Qk2LmN4Rt7Wx1Yz3Aa5/test';
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.asklucy.eu/v1/org/mcp-servers/mcp_8Qk2LmN4Rt7Wx1Yz3Aa5/test \
  --header 'Authorization: Bearer <token>'

Connects now, lists the tools and keeps them. A tool whose description, input schema or annotations changed since an admin last reviewed it is changed: it stays at ask (or stricter) for everyone, and is denied to agents, until an admin reviews it (reviewOrgMcpServerTools). New tools are listed as changed too. The answer is 200 whatever the server said: see status and last_error.

Authorizations

zitadel

Parameters

Path Parameters

serverId

required

string

Example

mcp_8Qk2LmN4Rt7Wx1Yz3Aa5

Responses

200

application/json

object

required

string

name

required

string

server

required

The tool server’s name, the prefix of its tools for the model and in tool permissions (ToolPermission.server). Unique in the organization.

string

url

required

string format: uri

auth

required

How Lucy signs in to the server. Never the secret itself.

object

type

required

none: no sign-in. shared: “Shared by the organization”: one credential an admin gave, for everyone’s calls (on your own server: your key). oauth: each person (and each agent) signs in at the server themselves (startMcpConnection), with the MCP authorization spec.

string

Allowed values: none shared oauth

header

For shared, the header the credential goes in, e.g. Authorization or X-API-Key. Shown to the server’s owner (an admin for the organization’s, you for your own); members don’t get the organization’s.

string | null

hint

For shared, the credential’s last four characters, e.g. …a1b2.

string | null

enabled

required

boolean

status

required

string

Allowed values: untested ok error

last_error

required

Why the last test failed, in a sentence (never the server’s whole answer).

string | null

last_checked_at

required

string | null format: date-time

tools

required

Array<object>

object

name

required

The tool’s name on the server (the model sees <server>.<name>).

string

title

required

string

description

required

As the server describes it to the model (cut at 2,000 characters here).

string

input_schema

The arguments the server asks for (JSON Schema).

object

key

additional properties

any

hints

required

object

read_only

required

boolean

destructive

required

boolean

open_world

required

boolean

changed

required

New, or its description, schema or annotations changed since an admin last reviewed it. It stays at ask or stricter, and denied to agents, until reviewed.

boolean

mine

Your own server (createMcpServer), not the organization’s.

boolean

connection

One of:

object
null

A principal’s own sign-in at an MCP server where each person signs in. Never a token.

object

status

required

string

Allowed values: active reauth

account

The account, when the server’s tokens say it.

string | null

connected_at

required

string format: date-time

last_used_at

required

string | null format: date-time

created_by

One of:

object
null

object

required

Zitadel user ID.

string

name

required

string

email

string | null format: email

kind

service is a customer system’s Zitadel service user; agent is a service agent (its ID is the agt_ ID), the author of its runs’ messages.

string

Allowed values: person service agent

created_at

required

string format: date-time

updated_at

required

string format: date-time

Example

{
  "id": "mcp_8Qk2LmN4Rt7Wx1Yz3Aa5",
  "name": "Acme CRM",
  "server": "acme_crm",
  "url": "https://mcp.acme.example/mcp",
  "auth": {
    "type": "none",
    "header": "Authorization"
  },
  "status": "untested",
  "connection": {
    "status": "active"
  },
  "created_by": {
    "kind": "person"
  }
}

401

Missing, expired or invalid token.

application/problem+json

RFC 9457 problem details.

object

type

required

string format: uri-reference

title

required

string

status

required

integer

detail

string

instance

string

request_id

string

quota

For quota-exceeded, the window that is used up.

object

window

required

string

Allowed values: five_hours week month

percent_used

required

number

<= 100

resets_at

required

Null for a rolling window that hasn’t started.

string | null format: date-time

limited_by

required

organization when the organization’s budget is closer to running out than the member’s own limit.

string

Allowed values: personal organization

request

One of:

object
null

A request as its member sees it, where they asked.

object

required

string

status

required

string

Allowed values: pending approved declined withdrawn

created_at

required

string format: date-time

decided_at

required

string | null format: date-time

note

required

What the admin who decided wrote back.

string | null

errors

Field-level problems (400 only).

Array<object>

object

field

required

JSON pointer into the request body.

string

message

required

string

Example

{
  "type": "https://docs.asklucy.eu/errors/answer-in-progress",
  "quota": {
    "window": "five_hours",
    "limited_by": "personal",
    "request": {
      "status": "pending"
    }
  }
}

Headers

X-Request-Id

string

Unique per request; quote it to support.

403

The token is valid but lacks the role this needs.

application/problem+json

RFC 9457 problem details.

object

type

required

string format: uri-reference

title

required

string

status

required

integer

detail

string

instance

string

request_id

string

quota

For quota-exceeded, the window that is used up.

object

window

required

string

Allowed values: five_hours week month

percent_used

required

number

<= 100

resets_at

required

Null for a rolling window that hasn’t started.

string | null format: date-time

limited_by

required

organization when the organization’s budget is closer to running out than the member’s own limit.

string

Allowed values: personal organization

request

One of:

object
null

A request as its member sees it, where they asked.

object

required

string

status

required

string

Allowed values: pending approved declined withdrawn

created_at

required

string format: date-time

decided_at

required

string | null format: date-time

note

required

What the admin who decided wrote back.

string | null

errors

Field-level problems (400 only).

Array<object>

object

field

required

JSON pointer into the request body.

string

message

required

string

Example

{
  "type": "https://docs.asklucy.eu/errors/answer-in-progress",
  "quota": {
    "window": "five_hours",
    "limited_by": "personal",
    "request": {
      "status": "pending"
    }
  }
}

Headers

X-Request-Id

string

Unique per request; quote it to support.

404

No such object in your organization.

application/problem+json

RFC 9457 problem details.

object

type

required

string format: uri-reference

title

required

string

status

required

integer

detail

string

instance

string

request_id

string

quota

For quota-exceeded, the window that is used up.

object

window

required

string

Allowed values: five_hours week month

percent_used

required

number

<= 100

resets_at

required

Null for a rolling window that hasn’t started.

string | null format: date-time

limited_by

required

organization when the organization’s budget is closer to running out than the member’s own limit.

string

Allowed values: personal organization

request

One of:

object
null

A request as its member sees it, where they asked.

object

required

string

status

required

string

Allowed values: pending approved declined withdrawn

created_at

required

string format: date-time

decided_at

required

string | null format: date-time

note

required

What the admin who decided wrote back.

string | null

errors

Field-level problems (400 only).

Array<object>

object

field

required

JSON pointer into the request body.

string

message

required

string

Example

{
  "type": "https://docs.asklucy.eu/errors/answer-in-progress",
  "quota": {
    "window": "five_hours",
    "limited_by": "personal",
    "request": {
      "status": "pending"
    }
  }
}

Headers

X-Request-Id

string

Unique per request; quote it to support.