MCP gateway API reference

Every MCP gateway route: directory, connections, accounts and connect links, toolsets and their MCP endpoint, approvals, the trace and OAuth for MCP clients.

#Routes

Management routes under /api/v1/organizations/{org} take a console session token and the permission shown; unknown ids answer 404, never 403. Routes under /v1 take an API key with the scope shown. The toolset endpoint also accepts Yelno MCP OAuth tokens. Errors use the gateway's error envelope, except the OAuth protocol endpoints (RFC 6749 and RFC 7591 shapes) and the MCP endpoint (JSON-RPC). Platform staff have their own routes under /api/v1/admin/mcp for the directory, host blocks, kill switches and pricing (setting a per-call price, or ending an organization's override with DELETE /api/v1/admin/mcp/pricing/{organization_id}?reason=); they are not listed here.

Two browser pages complete the picture: the hosted connect page at /mcp/connect/{token} and the OAuth consent screen at /mcp/oauth/authorize. Ids and amounts in the examples below are illustrative. The walk-through is in the MCP gateway guide.

#Directory

GET /api/v1/mcp/directory is public and returns {data: DirectoryEntryOut[]}, active entries only, filtered by ?category= and ?q=. GET /api/v1/mcp/directory/{id_or_slug} returns one, or 404 when it is disabled or unknown. Each entry was verified against the vendor's own documentation (source_url, verified_at). To connect one, create a connection with its directory_entry_id.

{ "id": "mcpd_…", "slug": "linear", "name": "Linear", "publisher": "Linear",
  "description": "Issues, projects and cycles in your Linear workspace.",
  "category": "productivity",         // developer | productivity | payments | data | search | knowledge
                                      // | design | crm | support | cloud | automation | ai
  "icon_slug": "linear",
  "server_url": "https://mcp.linear.app/mcp",
  "transport": "streamable_http",     // the only transport supported
  "auth_type": "oauth2",              // none | bearer | header | oauth2
  "auth_header_name": null,           // for auth_type header, e.g. "x-api-key"
  "alt_auth": ["bearer"],             // other credential kinds the server accepts
  "client_registration": "auto",      // oauth2: auto | preregistered (needs a client id and secret)
  "has_platform_client": false,       // staff stored an OAuth client for this entry
  "docs_url": "https://linear.app/docs/mcp",
  "notes": "…",
  "requires_vendor_approval": false,  // the vendor only admits approved clients
  "state": "active",
  "verified_at": "…", "source_url": "https://linear.app/docs/mcp" }

#Connections

{ "id": "mcpcn_…", "organization_id": "org_…", "slug": "github", "name": "GitHub",
  "description": null,
  "server_url": "https://api.githubcopilot.com/mcp/", "host": "api.githubcopilot.com",
  "transport": "streamable_http",
  "auth_type": "oauth2",              // none | bearer | header | oauth2
  "auth_header_name": null,
  "ownership": "organization",        // organization | end_user
  "directory_entry_id": "mcpd_…", "directory_slug": "github",
  "enabled": true,                    // your kill switch
  "staff_disabled": false,            // platform kill switch; calls refused while true
  "status": "healthy",                // pending | healthy | degraded | unhealthy | needs_auth | needs_reauth | disabled
  "status_detail": null,              // {code, message} when not healthy
  "protocol": { "era": "legacy", "version": "2025-06-18" },
  "oauth": { "issuer": "…", "client_registration": "preregistered", "scopes": ["repo"], "has_client_secret": true },
  "account": { … },                   // organization ownership: its one account, or null
  "accounts_count": 0,                // end_user ownership: connected accounts
  "tools_count": 41, "tools_refreshed_at": "…", "last_checked_at": "…", "next_check_at": "…",
  "last_used_at": "…",
  "rate_limit_per_minute": null,      // null: no per-connection limit
  "call_timeout_seconds": 30,         // 1 to 120
  "created_by": "user_…", "created_at": "…", "updated_at": "…", "version": 3 }

{ "id": "mcpa_…", "connection_id": "mcpcn_…",
  "external_user_id": null,           // null: the organization's account
  "status": "active",                 // active | needs_reauth | revoked
  "credential_hint": "Bearer ••••3f9a",   // OAuth: "OAuth (repo, read:org)"; never the secret
  "oauth": { "scopes": ["repo"], "expires_at": "…", "refreshable": true },   // or null
  "created_at": "…", "updated_at": "…", "last_used_at": "…" }

POST /api/v1/organizations/{org}/mcp/connections creates one and answers 201 with the connection:

{ "name": "GitHub", "slug": "github",            // slug optional; [a-z0-9][a-z0-9-]{0,47}
  "directory_entry_id": "mcpd_…",                     // OR server_url (+ transport, auth_type)
  "server_url": "https://mcp.example.com/mcp",        // https; no user info; no fragment
  "transport": "streamable_http",                     // "sse" is 400 mcp_transport_unsupported
  "auth_type": "bearer",
  "ownership": "organization",
  "credential": { "token": "…" },                     // bearer: {token}; header: {header_name, value}
  "oauth": { "client_id": "…", "client_secret": "…", "scopes": ["repo"] },   // optional pre-registered client
  "rate_limit_per_minute": 120, "call_timeout_seconds": 30,
  "reason": "…" }

// 400 when an approval policy covers data_policy.relax
{ "error": { "type": "invalid_request", "code": "approval_required",
             "param": "approval_request_id", "message": "…",
             "approval_request_id": "apr_…" } }

// once approved, send the same request again with
X-Yelno-Approval: <approval_request_id>

• Give directory_entry_id or server_url. With an entry, URL, transport, auth type and header name come from it.
• Only the Streamable HTTP transport is supported: transport: "sse" is 400 mcp_transport_unsupported.
• Registering a connection lets the gateway send data to a new host, so it is a data-policy relaxation. Under an enabled data_policy.relax approval policy, create (and a PATCH that changes server_url) answers 400 approval_required with error.approval_request_id, and applies once resubmitted with X-Yelno-Approval. A blocked host is 403 mcp_host_blocked.
• credential is valid only for an organization connection with bearer ({token}) or header ({header_name, value}) auth; values are single-line and up to 8 KiB; the header name must be an HTTP token and not a transport header (Host, Content-*, Mcp-*, X-Yelno-Hop, …).
• For none, bearer and header organization connections the create runs a health check within call_timeout_seconds; a failure returns the connection unhealthy, not an error. oauth2 connections start needs_auth.
• Up to 100 connections per organization (400 mcp_limit_reached). Other errors: mcp_server_url_invalid, mcp_slug_taken, mcp_directory_entry_unavailable, version_conflict. Changes are audited as mcp_connection.create, update and delete, with credential_set: true|false instead of any secret.

PATCH …/connections/{id} accepts name, description, slug, enabled, rate_limit_per_minute, call_timeout_seconds, server_url (a data-policy relaxation, like create), credential, oauth, version and reason. DELETE answers {id, deleted: true}: it revokes upstream OAuth tokens (best effort), deletes accounts, flows and links, and removes the connection from every toolset. POST …/check runs a health check and returns a HealthCheckOut; POST …/refresh-tools returns {tools_count, tools_refreshed_at}.

{ "name": "create_issue", "title": "…", "description": "…",
  "input_schema": { … }, "output_schema": { … },
  "annotations": { "readOnlyHint": false, "destructiveHint": true },
  "read_only": false,                 // annotations.readOnlyHint === true
  "destructive": true,                // !read_only && annotations.destructiveHint !== false
  "approval_default": true }

{ "id": "mcph_…", "connection_id": "mcpcn_…", "checked_at": "…",
  "status": "ok",                     // ok | error | auth_required
  "latency_ms": 212, "tools_count": 41, "error_code": null,
  "protocol_version": "2025-06-18", "era": "legacy" }

POST …/connections/{id}/oauth/start
{ "external_user_id": "user-42",   // optional: an end user's account
  "for_me": false,                 // true: connect your own account (stored as yelno_user:<id>)
  "return_to": "…" }               // optional; a console page (else 400); default /console/mcp/connections/{id}
→ { "flow_id": "mcpf_…", "authorize_url": "https://…", "expires_at": "…" }

return_to must be a page of the console's origin, else 400. The browser returns from the vendor to GET /api/v1/mcp/oauth/callback, which redirects to return_to with ?mcp_oauth=connected|error&connection={id}&error_code=…. For a connect link it redirects to the link's return_url, or without one to the hosted page /mcp/connect/{token}, never to the console. The vendor's error text is never echoed. GET /api/v1/mcp/oauth/client-metadata.json is the client metadata document Yelno presents to vendors that support it (client_name: "Yelno MCP Gateway", public client, authorization_code and refresh_token grants).

#Accounts and connect links

GET …/connections/{id}/accounts lists ConnectedAccountOut rows (?external_user_id=). PUT …/connections/{id}/accounts/{external_user_id} with {"credential": {…}} sets an end user's bearer or header credential. DELETE …/connections/{id}/accounts/{account_id} revokes one account, with upstream revocation where possible. External user ids are 1 to 256 characters of [A-Za-z0-9._:@|-] (400 mcp_external_user_invalid otherwise).

POST /api/v1/organizations/{org}/mcp/connections/{id}/connect-links
POST /v1/mcp/connect-links                      // body adds "connection": "<id|slug>"
{ "external_user_id": "user-42",
  "return_url": "https://app.example.com/settings/integrations",   // optional; https
  "expires_in_seconds": 3600 }                  // 60 to 604800, default 3600
→ 201 { "id": "mcpl_…", "url": "https://yelno.ai/mcp/connect/ymcl_…", "token": "ymcl_…",
        "connection_id": "mcpcn_…", "external_user_id": "user-42", "expires_at": "…" }

The token is shown once; the link is single use and consumed when the account connects. A link for a user who already has an account replaces that account. Links are valid only for end-user connections with bearer, header or oauth2 auth; an organization connection's single account is authorized from the console (400 mcp_connect_link_invalid otherwise). GET …/connections/{id}/connect-links lists links still pending.

GET /api/v1/mcp/connect/{token}
{ "connection": { "name": "Linear", "auth_type": "oauth2", "auth_header_name": null,
                  "directory": { "name": "Linear", "icon_slug": "linear", "docs_url": "…" } },
  "organization": { "name": "Acme" },
  "external_user_id": "user-42",
  "state": "pending",                 // pending | connected | expired
  "expires_at": "…" }

POST /api/v1/mcp/connect/{token}/start        → { "authorize_url": "https://…" }
POST /api/v1/mcp/connect/{token}/credential   { "value": "…" }
                                              → { "state": "connected", "return_url": "…" }

Unknown tokens answer 404. The credential route checks the value with tools/list first (400 mcp_credential_rejected). Attempts are limited to 10 per link and 30 per minute per source IP (429 rate_limited). After an OAuth sign-in the user lands on the link's return_url with ?mcp_oauth=connected|error (and error_code), or on the hosted page itself when there is none. The hosted page reads state: "connected" even after the link is spent. Connections are audited as mcp_account.connect with via: "connect_link".

#Toolsets

{ "id": "mcpts_…", "organization_id": "org_…", "slug": "eng-agents", "name": "Engineering agents",
  "description": null, "enabled": true, "staff_disabled": false,
  "read_only": false,
  "approval_mode": "destructive",     // destructive (default) | always | never
  "elicitation_approvals": true,      // in-place approval for OAuth callers
  "elicitation_for_api_keys": false,  // ...and for API-key callers (off: automation could approve itself)
  "redact_secrets": true,
  "flag_prompt_injection": true,
  "include_yelno_tools": false,       // API-key callers only
  "rate_limit_per_minute": 600,       // per calling principal; null = platform default (600)
  "project_ids": [], "api_key_ids": [],   // empty = any key of the organization
  "oauth_enabled": true,
  "members": [
    { "connection_id": "mcpcn_…", "connection_slug": "github", "connection_name": "GitHub",
      "namespace": "github",          // [a-z0-9][a-z0-9_-]{0,31}
      "allowed_tools": null,          // null = every tool
      "denied_tools": ["delete_repository"],
      "approval_required": ["create_pull_request"],
      "approval_exempt": ["search_issues"],
      "rate_limit_per_minute": null } ],
  "endpoint_url": "https://yelno.ai/v1/mcp/toolsets/mcpts_…",
  "resource_metadata_url": "https://yelno.ai/.well-known/oauth-protected-resource/v1/mcp/toolsets/mcpts_…",
  "tools_count": 37, "version": 4, "created_by": "user_…", "created_at": "…", "updated_at": "…" }

POST …/mcp/toolsets takes the writable fields above plus reason. PATCH …/mcp/toolsets/{id} takes any writable field; members replaces the whole list, and version is checked (400 version_conflict). DELETE revokes the toolset's OAuth grants and tokens. Up to 50 toolsets per organization (400 mcp_limit_reached) and 20 members per toolset (400 invalid_request, param: "members"). Other errors: mcp_namespace_invalid, mcp_namespace_taken, mcp_connection_not_found, mcp_slug_taken, mcp_slug_invalid, version_conflict. Audited as mcp_toolset.create, update and delete.

Approval rule per tool, first match wins: approval_required, then approval_exempt, then approval_mode (always, never, or destructive: approval unless readOnlyHint: true or destructiveHint: false). Tools are exposed as <namespace>__<tool>; a name outside [A-Za-z0-9_.-] or over 128 characters is made safe (other characters become _, truncated, de-duplicated with _2, _3) and mapped back.

With read_only on, tools that are not read-only are unlisted, and calling one is JSON-RPC -32602 like any filtered tool. elicitation_approvals lets people signed in with OAuth approve a call in their client; elicitation_for_api_keys extends that to API-key callers and is off by default, because a headless automation could approve its own calls.

{ "name": "github__create_issue", "namespace": "github", "connection_id": "mcpcn_…",
  "upstream_name": "create_issue", "title": "…", "description": "…",
  "annotations": { … }, "read_only": false, "approval_required": true, "input_schema": { … } }

#Toolset MCP endpoint

Streamable HTTP, stateless. No session id is issued and a received Mcp-Session-Id is ignored. Each request gets one application/json JSON-RPC message; a body of only notifications or responses gets 202 with no body; legacy batches get an array. GET and DELETE answer 405 with Allow: POST. A browser Origin other than the console's gets 403. Because the endpoint is stateless, initialize is optional: tools/list and tools/call work without it.

Authentication. Authorization: Bearer yk_live_… (or yk_test_…, or x-api-key) with mcp:toolset or inference:invoke, from the toolset's organization (another organization's key gets 404, -32600) and inside its project and key scoping (403, -32001 with data.error.code mcp_toolset_key_not_allowed). Or Authorization: Bearer ymcp_at_…, a live MCP OAuth token whose resource is this toolset's URL, from an active grant whose member still holds key:create. Management tokens are refused with 401. A disabled toolset is 403 with data.error.code mcp_toolset_disabled; an organization the platform switched off is 403 with mcp_gateway_disabled. The full status table is under Errors.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="yelno", resource_metadata="https://yelno.ai/.well-known/oauth-protected-resource/v1/mcp/toolsets/mcpts_…", scope="mcp:toolset"

{ "jsonrpc": "2.0", "id": 1, "error": { "code": -32001, "message": "…" } }

Without oauth_enabled, the challenge omits resource_metadata.

Protocol versions. Modern 2026-07-28 and legacy 2025-11-25, 2025-06-18 and 2025-03-26. Legacy: initialize echoes a supported requested version, else 2025-11-25; then notifications/initialized (202), ping, tools/list, tools/call; an MCP-Protocol-Version header naming an unsupported version gets 400. Modern: requests carry params._meta["io.modelcontextprotocol/protocolVersion"]; the MCP-Protocol-Version, Mcp-Method and (for tools/call) Mcp-Name headers must match the body (400, -32020); an unsupported version is 400 -32022 with data: {supported, requested}. Every modern result carries resultType. Capabilities are {"tools": {"listChanged": false}}; resources/* and prompts/* are not offered.

{ "resultType": "complete",
  "supportedVersions": ["2026-07-28", "2025-11-25", "2025-06-18", "2025-03-26"],
  "capabilities": { "tools": { "listChanged": false } },
  "instructions": "…",               // lists the namespaces
  "_meta": { "io.modelcontextprotocol/serverInfo": { "name": "yelno-toolset", "title": "Engineering agents", "version": "1.0" } },
  "ttlMs": …, "cacheScope": "private" }

tools/list aggregates every enabled member's cached tools, filtered by allowed_tools, denied_tools, read-only mode and the caller's accounts, in member order then upstream order, 100 per page with an opaque nextCursor. Yelno's own tools come first when include_yelno_tools is on (API-key callers). Each tool keeps its upstream inputSchema, outputSchema, annotations, title, icons and description (up to 4,000 characters) under its namespaced name, and _meta gains "io.yelno/approval": "required" | "none". Modern results carry ttlMs: 60000 and cacheScope: "private".

tools/call checks, in order (the first failure decides):

Result forwarding. text, image and audio content (base64 up to 1 MB each), resource_link and resource (embedded text or blob up to 1 MB) pass through. A larger media item becomes a text note such as [image omitted by the gateway: 3.2 MB exceeds 1 MB]. structuredContent passes through up to 1 MB, else it is dropped with a note. An upstream isError: true result passes through as-is. Results carry _meta["io.yelno/call_id"] and, when output was flagged, _meta["io.yelno/flags"].

Gateway tool errors are results with isError: true, a readable content text, and structuredContent.error = {code, message, …} (codes under Errors). An upstream isError result passes through unchanged and is traced as mcp_tool_error:

{ "jsonrpc": "2.0", "id": 3, "result": {
  "isError": true,
  "content": [{ "type": "text", "text": "…" }],
  "structuredContent": { "error": { "code": "mcp_rate_limited", "message": "…", "retry_after_seconds": 12 } },
  "_meta": { "io.yelno/call_id": "mcpc_…" } } }

#Approvals

GET …/mcp/approvals (approval:read) lists {data: ApprovalOut[]}, filtered by ?status=pending|approved|denied|expired|used, ?toolset_id= and ?limit=; GET …/approvals/{id} returns one. POST …/approvals/{id}/approve (approval:decide) takes {always_allow?: false, reason?}; always_allow also adds the tool to the member's approval_exempt (an audited toolset update). POST …/approvals/{id}/deny takes {reason?}. Deciding an approval that is not pending is 409 mcp_approval_decided. Decisions are audited as mcp_approval.approve and deny.

{ "id": "mcpap_…", "organization_id": "org_…", "toolset_id": "mcpts_…", "toolset_name": "Engineering agents",
  "connection_id": "mcpcn_…", "connection_name": "GitHub",
  "tool": "github__create_issue", "upstream_tool": "create_issue",
  "arguments_sha256": "…",
  "arguments": null,                  // only while content capture for the mcp surface is on
  "external_user_id": "user-42",
  "requested_by": { "kind": "api_key", "api_key_id": "key_…", "user_id": null, "client_name": null },
  "status": "pending",                // pending | approved | denied | expired | used
  "decided_by": null, "decided_at": null, "decided_via": null,   // console | elicitation
  "reason": null, "always_allow": false,
  "expires_at": "…", "approved_until": null, "used_at": null, "call_id": null,
  "approval_url": "https://yelno.ai/console/mcp/approvals/mcpap_…", "created_at": "…" }

An approved call must be retried within 15 minutes (approved_until); a pending approval expires after 24 hours; each approval runs at most one call, and the call's trace row carries approval_id. In-place approval by elicitation goes to OAuth callers on modern clients when elicitation_approvals is on, and to API-key callers only with elicitation_for_api_keys; everyone else gets the mcp_approval_required tool error with the approval_url. Approvals for Responses references use the Responses round trip instead.

#Trace and statistics

GET /api/v1/organizations/{org}/mcp-calls (usage:read) takes the filters connection_id, toolset_id, tool_name, status, surface, since and until (ISO 8601), and cursor (the last row id of the previous page), alongside the existing response_id, request_id and limit. The answer carries next_cursor, null on the last page. Rows add surface (responses or gateway), connection_id, toolset_id, external_user_id, oauth_client_id, approval_id, bytes_in (received from the upstream server), bytes_out (sent to it), charge_nanos (a string) and flags (for example ["prompt_injection", "secret_redacted"]). For gateway rows, response_id is the gateway request id (mcpg_…), server_label the toolset slug, server_host the upstream host and kind list_tools or call_tool. Rate-limit and kill-switch refusals are refused with an error_code. Rows never hold arguments, outputs or credentials.

GET /api/v1/organizations/{org}/mcp/stats?since=…&until=…&group_by=tool
{ "since": "…", "until": "…", "group_by": "tool",     // connection | toolset | tool | day
  "totals": { "calls": 120, "errors": 4, "error_rate": 0.0333, "p50_ms": 210, "p95_ms": 1300,
              "bytes_in": 912345, "charged_nanos": "0" },
  "rows": [ { "key": { "connection_id": "mcpcn_…", "connection_name": "GitHub", "tool": "github__search_issues" },
              "calls": 80, "errors": 1, "error_rate": 0.0125, "p50_ms": 180, "p95_ms": 900 } ] }

The window defaults to the last 7 days and can span up to 93. Only call_tool rows count; errors is failed plus refused. Row keys depend on group_by: {day: "YYYY-MM-DD"}, {toolset_id, toolset_name}, {connection_id, connection_name}, and for tool the connection plus tool.

#OAuth for MCP clients

For clients that sign in with OAuth (Claude and ChatGPT connectors, Cursor, VS Code), Yelno is the authorization server. The issuer is https://yelno.ai. Tokens are opaque and bound to one toolset URL: they are valid only at that toolset's endpoint and never accepted by the management API. Both metadata documents are public; the protected-resource document is 404 for unknown toolsets and toolsets with oauth_enabled off. /.well-known/openid-configuration is not served.

Edge routing. In a deployment, the web edge must send GET /.well-known/oauth-authorization-server (exact path) and every path under /.well-known/oauth-protected-resource/ to the API, in addition to /api/* and /v1/*. Everything else (registration, token, revocation, the consent API, the callback, the client metadata document, the toolset endpoints) is already under /api/v1 or /v1. /mcp/oauth/authorize and /mcp/connect/{token} are pages of the web app.

GET /.well-known/oauth-protected-resource/v1/mcp/toolsets/{id}
{ "resource": "https://yelno.ai/v1/mcp/toolsets/mcpts_…", "authorization_servers": ["https://yelno.ai"],
  "scopes_supported": ["mcp:toolset"], "bearer_methods_supported": ["header"],
  "resource_name": "Yelno MCP toolset", "resource_documentation": "https://yelno.ai/docs/mcp-gateway" }

GET /.well-known/oauth-authorization-server
{ "issuer": "https://yelno.ai",
  "authorization_endpoint": "https://yelno.ai/mcp/oauth/authorize",
  "token_endpoint": "https://yelno.ai/api/v1/mcp/oauth/token",
  "registration_endpoint": "https://yelno.ai/api/v1/mcp/oauth/register",
  "revocation_endpoint": "https://yelno.ai/api/v1/mcp/oauth/revoke",
  "response_types_supported": ["code"], "response_modes_supported": ["query"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"],
  "revocation_endpoint_auth_methods_supported": ["none"],
  "scopes_supported": ["mcp:toolset"],
  "client_id_metadata_document_supported": true,
  "authorization_response_iss_parameter_supported": true,
  "service_documentation": "https://yelno.ai/docs/mcp-gateway" }

Client registration. A client can use an https:// client_id with a path that points to its client metadata document: it is fetched through the network guard (up to 16 KiB, cached 24 hours), its client_id must equal the URL exactly, it needs client_name and redirect_uris, and the consent screen shows the client's host as verified. Or it can register dynamically (deprecated in the MCP specification, still supported). Only public clients are issued: a requested client_secret_* method is answered with none. Redirect URIs (1 to 10) must be https, loopback http (127.0.0.1, [::1] or localhost, any port) or, for application_type: "native", a private-use scheme; no fragments. Registration is limited to 5 per minute per source IP and 100 per minute platform-wide; over that, 429 {"error": "slow_down"} with Retry-After. Clients with no grant are deleted after 30 days.

POST /api/v1/mcp/oauth/register
{ "client_name": "Claude", "redirect_uris": ["https://claude.ai/api/mcp/auth_callback"],
  "grant_types": ["authorization_code", "refresh_token"], "response_types": ["code"],
  "token_endpoint_auth_method": "none", "application_type": "web", "client_uri": "…", "logo_uri": "…" }
→ 201 { "client_id": "ymc_…", "client_id_issued_at": 1760000000, "client_name": "Claude",
        "redirect_uris": [ … ], "grant_types": [ … ], "response_types": ["code"],
        "token_endpoint_auth_method": "none", "application_type": "web" }

Authorize. The client opens https://yelno.ai/mcp/oauth/authorize with response_type=code, client_id, redirect_uri, state, code_challenge, code_challenge_method=S256, scope=mcp:toolset and resource (the toolset URL). The page signs the person in if needed and calls the consent API. Validation failures are 400 invalid_request with a code; nothing is ever redirected to an unvalidated URI. invalid_target covers a resource that is not a toolset URL, a toolset with OAuth off, or a toolset the person cannot use (they must be a member of its organization holding key:create). Older clients that send no resource get toolsets to choose from.

GET /api/v1/mcp/oauth/authorize?response_type=code&client_id=…&redirect_uri=…&state=…
    &code_challenge=…&code_challenge_method=S256&scope=mcp:toolset&resource=…
{ "client": { "client_id": "ymc_…", "name": "Claude", "kind": "dcr",      // dcr | cimd
              "verified_host": null, "client_uri": null, "logo_uri": null },
  "redirect_uri": "…", "state": "…",
  "scopes": [{ "name": "mcp:toolset", "description": "Use the tools of this toolset on your behalf" }],
  "toolset": { "id": "mcpts_…", "name": "Engineering agents", "organization": { "id": "org_…", "name": "Acme" },
               "tools_count": 37, "connections": [{ "name": "GitHub", "ownership": "end_user", "connected": false }] },
  "toolsets": [ … ],                  // choices when resource was absent
  "existing_grant": null }

POST /api/v1/mcp/oauth/authorize
{ "decision": "allow", "client_id": "…", "redirect_uri": "…", "scope": "mcp:toolset", "state": "…",
  "code_challenge": "…", "code_challenge_method": "S256", "resource": "…", "toolset_id": "…" }
→ { "redirect_to": "<redirect_uri>?code=…&state=…&iss=https://yelno.ai" }

Allow creates or updates the grant (client, person, toolset) and issues a single-use code valid for 10 minutes; deny redirects with error=access_denied. Grants are audited as mcp_oauth_grant.create.

POST /api/v1/mcp/oauth/token     (form or JSON; client_id in the body)
grant_type=authorization_code&code=…&redirect_uri=…&code_verifier=…&client_id=…&resource=…
grant_type=refresh_token&refresh_token=…&client_id=…

→ { "access_token": "ymcp_at_…", "token_type": "Bearer", "expires_in": 3600,
    "refresh_token": "ymcp_rt_…", "scope": "mcp:toolset" }

→ 400 { "error": "invalid_grant", "error_description": "…" }

When resource is sent with the code, it must equal the grant's toolset URL. Access tokens live 1 hour and refresh tokens 30 days, and refresh tokens rotate: reusing a rotated refresh token revokes every token of the grant. Only hashes are stored. Errors use the flat RFC 6749 shape with status 400 (invalid_client 401). POST /api/v1/mcp/oauth/revoke takes token and client_id and always answers 200.

GET /api/v1/organizations/{org}/mcp/oauth-grants
{ "data": [ { "id": "mcpog_…", "client_id": "ymc_…", "client_name": "Claude", "client_kind": "dcr",
              "user_id": "user_…", "email": "…", "toolset_id": "mcpts_…", "toolset_name": "Engineering agents",
              "state": "active", "created_at": "…", "last_used_at": "…", "live_tokens": 2 } ] }

POST …/mcp/oauth-grants/{id}/revoke (policy:update) revokes a grant and its tokens, audited. Each person can list their own grants (same row shape) at GET /api/v1/mcp/oauth/grants and revoke one with POST /api/v1/mcp/oauth/grants/{id}/revoke, which answers {id, state: "revoked"}.

#Backend routes

For your own backend, with an API key that has the mcp:connect scope: create connect links for your users, see which accounts they connected and revoke them. X-Yelno-External-User on the toolset endpoint and on /v1/responses picks an account within the key's organization only; it never selects a tenant, and it is not accepted from OAuth callers. A key without mcp:connect gets 403 insufficient_scope.

GET /v1/mcp/connections
{ "data": [ { "id": "mcpcn_…", "slug": "linear", "name": "Linear", "auth_type": "oauth2",
              "ownership": "end_user", "status": "healthy", "tools_count": 23 } ] }

GET /v1/mcp/accounts?connection=linear&external_user_id=user-42
{ "data": [ ConnectedAccountOut ] }

DELETE /v1/mcp/accounts/mcpa_…

The connect-link body is the one in Accounts and connect links, plus connection (id or slug). Revoking an account asks the vendor to revoke its tokens, best effort.

#Webhook events

Four events in the mcp category of the webhook catalog. Subscribe a webhook endpoint to them, or to mcp.*.

// mcp.connection.unhealthy · mcp.connection.needs_reauth · mcp.connection.recovered
{ "connection_id": "mcpcn_…", "connection_slug": "github", "name": "GitHub",
  "status": "needs_reauth", "previous_status": "healthy", "error_code": "…",
  "account_id": "mcpa_…", "external_user_id": "user-42",   // when one account is affected
  "checked_at": "…" }

// mcp.approval.requested (never carries the arguments)
{ "approval_id": "mcpap_…", "toolset_id": "mcpts_…", "connection_id": "mcpcn_…",
  "tool": "github__create_issue", "external_user_id": "user-42",
  "approval_url": "https://yelno.ai/console/mcp/approvals/mcpap_…", "expires_at": "…" }

#Errors

Management and /v1 key routes answer the standard error envelope, {"error": {type, message, code, param, …}}. The OAuth protocol endpoints use the RFC 6749 and RFC 7591 shapes described above.

The toolset endpoint answers JSON-RPC:

Gateway refusals and upstream failures answer HTTP 200 with a result whose isError is true and whose structuredContent.error.code is one of these. An upstream isError result passes through unchanged.