MCP connections API

Application boundary#

These paths belong to your YAADMIN installation. They are not callable product-website APIs. Authenticated mutations require a session-matched X-CSRF-Token unless the route is public. Handler-local error codes are not exhaustive downstream schemas.

Verified routes#

Find a route in this category

15 routes

GET/settings/mcp

Mcp settings page.

Authentication: session + administrator role
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: none
Query parameters: none explicitly read
Headers: none beyond shared session/CSRF
Response structure: HTML template response (handler names the template)
Important errors: none literal; shared/helper errors apply
Approval behavior: no standalone approval behavior in this handler.

Verified route registration · handler mcp_settings_page. Some definitions may be partially redacted; no missing fields are inferred.

GET/api/mcp/registry

Mcp registry.

Authentication: session + administrator role
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: none
Query parameters: q="", cursor="", limit=24
Headers: none beyond shared session/CSRF
Response structure: await asyncio.to_thread(mcp_registry_search, q, cursor=cursor, limit=limit)
Important errors: none literal; shared/helper errors apply
Approval behavior: no standalone approval behavior in this handler.

Verified route registration · handler api_mcp_registry. Some definitions may be partially redacted; no missing fields are inferred.

GET/api/mcp/registry/plan

Mcp registry plan.

Authentication: session + administrator role
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: none
Query parameters: method="", name (required)
Headers: none beyond shared session/CSRF
Response structure: await asyncio.to_thread(mcp_registry_install_plan, name, method)
Important errors: none literal; shared/helper errors apply
Approval behavior: no standalone approval behavior in this handler.

Verified route registration · handler api_mcp_registry_plan. Some definitions may be partially redacted; no missing fields are inferred.

GET/api/mcp/servers

Mcp servers.

Authentication: session + administrator role
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: none
Query parameters: none explicitly read
Headers: none beyond shared session/CSRF
Response structure: {servers}
Important errors: none literal; shared/helper errors apply
Approval behavior: no standalone approval behavior in this handler.

Verified route registration · handler api_mcp_servers. Some definitions may be partially redacted; no missing fields are inferred.

POST/api/mcp/servers/test

Mcp test.

Authentication: session + administrator role
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: MCPServerPayload [id, name, transport, command, args_json, env_json, url, headers_json, oauth_client_id, oauth_client_secret, clear_oauth_client_secret, auth_mode, read_only, timeout_seconds, original_id]
Query parameters: none explicitly read
Headers: none beyond shared session/CSRF
Response structure: {ok, auth_required, oauth_available, oauth_mode, challenge, http_status, auth}; {ok, auth_required, oauth_available, challenge, http_status, auth_error}; {ok, tool_count, tools}
Important errors: 400
Approval behavior: no standalone approval behavior in this handler.

Request fields

Field	Verified definition
`id`	`str`
`name`	`str = ""`
`transport`	`str = "stdio"`
`command`	`str = ""`
`args_json`	`str = "[]"`
`env_json`	`str \| None = None`
`url`	`str = ""`
`headers_json`	`str \| None = None`
`oauth_client_id`	`str = ""`
`oauth_client_secret`	`type/default redacted; field name verified`
`clear_oauth_client_secret`	`type/default redacted; field name verified`
`auth_mode`	`str = "shared"`
`read_only`	`bool = False`
`timeout_seconds`	`int = 30`
`original_id`	`str \| None = None`

Verified route registration · handler api_mcp_test. Some definitions may be partially redacted; no missing fields are inferred.

POST/api/mcp/oauth/start

Mcp oauth start.

Authentication: session + administrator role
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: MCPOAuthStartPayload [id, url, challenge]
Query parameters: none explicitly read
Headers: none beyond shared session/CSRF
Response structure: await asyncio.to_thread(mcp_oauth_begin, repo, server_id=sid, mcp_url=payload.url, challenge=payload.challenge, redirect_uri=redirect_uri, updated_by=identity.username)
Important errors: 400
Approval behavior: no standalone approval behavior in this handler.

Request fields

Field	Verified definition
`id`	`str`
`url`	`str`
`challenge`	`str`

Verified route registration · handler api_mcp_oauth_start. Some definitions may be partially redacted; no missing fields are inferred.

GET/api/mcp/oauth/callback

Mcp oauth callback.

Authentication: session + administrator role
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: none
Query parameters: code, error, error_description, state
Headers: none beyond shared session/CSRF
Response structure: HTMLResponse(f"<!doctype html><meta charset='utf-8'><title>YAADMIN MCP OAuth</title><style>body{{font:16px system-ui;padding:32px;max-width:720px;margin:auto}}.box{{borde
Important errors: none literal; shared/helper errors apply
Approval behavior: no standalone approval behavior in this handler.

Verified route registration · handler api_mcp_oauth_callback. Some definitions may be partially redacted; no missing fields are inferred.

PUT/api/mcp/servers/{server_id}

Mcp save.

Authentication: session + administrator role
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: MCPServerPayload [id, name, transport, command, args_json, env_json, url, headers_json, oauth_client_id, oauth_client_secret, clear_oauth_client_secret, auth_mode, read_only, timeout_seconds, original_id]
Query parameters: none explicitly read
Headers: none beyond shared session/CSRF
Response structure: {ok, server, runtime}
Important errors: 400, 409
Approval behavior: no standalone approval behavior in this handler.

Request fields

Field	Verified definition
`id`	`str`
`name`	`str = ""`
`transport`	`str = "stdio"`
`command`	`str = ""`
`args_json`	`str = "[]"`
`env_json`	`str \| None = None`
`url`	`str = ""`
`headers_json`	`str \| None = None`
`oauth_client_id`	`str = ""`
`oauth_client_secret`	`type/default redacted; field name verified`
`clear_oauth_client_secret`	`type/default redacted; field name verified`
`auth_mode`	`str = "shared"`
`read_only`	`bool = False`
`timeout_seconds`	`int = 30`
`original_id`	`str \| None = None`

Verified route registration · handler api_mcp_save. Some definitions may be partially redacted; no missing fields are inferred.

POST/api/mcp/servers

Mcp create.

Authentication: session + administrator role
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: MCPServerPayload [id, name, transport, command, args_json, env_json, url, headers_json, oauth_client_id, oauth_client_secret, clear_oauth_client_secret, auth_mode, read_only, timeout_seconds, original_id]
Query parameters: none explicitly read
Headers: none beyond shared session/CSRF
Response structure: {ok, server, runtime}
Important errors: 400
Approval behavior: no standalone approval behavior in this handler.

Request fields

Field	Verified definition
`id`	`str`
`name`	`str = ""`
`transport`	`str = "stdio"`
`command`	`str = ""`
`args_json`	`str = "[]"`
`env_json`	`str \| None = None`
`url`	`str = ""`
`headers_json`	`str \| None = None`
`oauth_client_id`	`str = ""`
`oauth_client_secret`	`type/default redacted; field name verified`
`clear_oauth_client_secret`	`type/default redacted; field name verified`
`auth_mode`	`str = "shared"`
`read_only`	`bool = False`
`timeout_seconds`	`int = 30`
`original_id`	`str \| None = None`

Verified route registration · handler api_mcp_create. Some definitions may be partially redacted; no missing fields are inferred.

DELETE/api/mcp/servers/{server_id}

Mcp delete.

Authentication: session + administrator role
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: none
Query parameters: none explicitly read
Headers: none beyond shared session/CSRF
Response structure: {ok, runtime}
Important errors: 400
Approval behavior: no standalone approval behavior in this handler.

Verified route registration · handler api_mcp_delete. Some definitions may be partially redacted; no missing fields are inferred.

GET/connections

Mcp connections page.

Authentication: session
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: none
Query parameters: none explicitly read
Headers: none beyond shared session/CSRF
Response structure: HTML template response (handler names the template)
Important errors: none literal; shared/helper errors apply
Approval behavior: no standalone approval behavior in this handler.

Verified route registration · handler mcp_connections_page. Some definitions may be partially redacted; no missing fields are inferred.

GET/api/connections/mcp

Mcp personal connections.

Authentication: session
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: none
Query parameters: none explicitly read
Headers: none beyond shared session/CSRF
Response structure: {connections}
Important errors: none literal; shared/helper errors apply
Approval behavior: no standalone approval behavior in this handler.

Verified route registration · handler api_mcp_personal_connections. Some definitions may be partially redacted; no missing fields are inferred.

POST/api/connections/mcp/{server_id}/oauth/start

Mcp personal oauth start.

Authentication: session
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: PersonalOAuthStartPayload [challenge]
Query parameters: none explicitly read
Headers: none beyond shared session/CSRF
Response structure: await asyncio.to_thread(oauth_begin, repo, server_id=sid, mcp_url=str(effective.get('url') or ''), challenge=oauth_challenge, redirect_uri=redirect_uri, updated_by=identi
Important errors: 400
Approval behavior: no standalone approval behavior in this handler.

Request fields

Field	Verified definition
`challenge`	`str = ""`

Verified route registration · handler api_mcp_personal_oauth_start. Some definitions may be partially redacted; no missing fields are inferred.

GET/api/connections/mcp/oauth/callback

Mcp personal oauth callback.

Authentication: session
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: none
Query parameters: code, error, error_description, state
Headers: none beyond shared session/CSRF
Response structure: HTMLResponse(f"<!doctype html><meta charset='utf-8'><title>YAADMIN Personal MCP OAuth</title><style>body{{font:16px system-ui;padding:32px;max-width:720px;margin:auto;bac
Important errors: none literal; shared/helper errors apply
Approval behavior: no standalone approval behavior in this handler.

Verified route registration · handler api_mcp_personal_oauth_callback. Some definitions may be partially redacted; no missing fields are inferred.

DELETE/api/connections/mcp/{server_id}

Mcp personal disconnect.

Authentication: session
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: none
Query parameters: none explicitly read
Headers: none beyond shared session/CSRF
Response structure: {ok, server_id, connected}
Important errors: 403, 404
Approval behavior: no standalone approval behavior in this handler.

Verified route registration · handler api_mcp_personal_disconnect. Some definitions may be partially redacted; no missing fields are inferred.

Implementation reference: 2026-10-02. Labels distinguish verified behavior, partial implementation and architectural intent.