Add a connector by URL

POST

/org/mcp-servers

const url = 'https://api.asklucy.eu/v1/org/mcp-servers';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"example","server":"example","url":"https://example.com","auth":{"type":"none","header":"example","secret":"example"}}'
};

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 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "server": "example", "url": "https://example.com", "auth": { "type": "none", "header": "example", "secret": "example" } }'

Adds a remote MCP server for everyone at the organization, and tests it at once: Lucy connects, lists its tools and keeps them (tools, status). Each tool gets a permission from its annotations (read-only: allow; anything else: ask), which admins change in setOrgToolPermission with the server’s server name.

The URL must be https, without a user name or password, on a public address: a name resolving to a private, loopback, link-local or otherwise reserved address is refused (400), now and on every connection. Sign-in (auth.type): none, or shared (“Shared by the organization”): an admin gives a header and its value (an API key or a bearer token), sealed in Lucy’s vault; everyone’s calls use that one account.

The server learns nothing about the organization or the person, beyond what its own sign-in tells it. Audited as mcp_server.created (never the secret).

Authorizations

zitadel

Request Body^required

application/json

object

name

required

string

>= 1 characters <= 60 characters

server

The tools’ prefix; from the name when left out. Not one of Lucy’s (m365, local, sandbox, web, memory).

string

/^[a-z][a-z0-9_]{1,31}$/

url

required

string format: uri

<= 2048 characters

auth

object

type

required

string

Allowed values: none shared oauth

header

For shared (default Authorization). Not a header Lucy sets itself (Host, Content-Type, …). In Authorization, a bare key (no scheme such as Bearer or Basic ) is sent as Bearer <key>.

string

<= 64 characters /^[A-Za-z0-9-]+$/

secret

For shared, the header’s value, e.g. Bearer sk_…. Sealed; never returned. Leave out on an update to keep the current one.

string

>= 1 characters <= 4096 characters

Responses

201

Added (see status for the test’s result).

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"
  }
}

400

The request is invalid; errors lists what’s wrong.

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.

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.

409

The object isn’t in a state that allows this (e.g. Lucy is already answering).

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.

Add a connector by URL

Authorizations

Request Bodyrequired

Responses

201

Example

400

Example

Headers

401

Example

Headers

403

Example

Headers

409

Example

Headers

Request Body^required