MCP Catalog & Connections

Agor can attach external MCP servers to individual sessions. Use Catalog for reviewed remote endpoints, or Settings → MCP Servers for configurations you manage yourself.

Open MCP Catalog from the header’s shop icon or the same icon in the session’s MCP popover. Search the session picker to find existing servers; its no-match action also opens the Catalog. Catalog Connect adds a server to My Servers, without creating a session. Choose Start new session afterward to select an eligible teammate and agent tool; its starter prompt opens in the composer as editable, unsent text. To attach a saved server to the current conversation, select it in that picker.

Defaults when starting a session

New sessions inherit the branch’s nonempty MCP Servers list, otherwise your user defaults. Quick start, the new-session form, mobile, and agor_sessions_create resolve those defaults on the daemon at creation time. If an inherited server has been removed, creation succeeds with the remaining servers and a warning. If every server in the branch list is missing, none are attached; Agor does not substitute user defaults. Permission failures, malformed configuration, and database failures still reject creation.

Editing the session’s MCP picker makes its whole list an explicit selection. Explicit selections are atomic: an unavailable or unauthorized server rejects creation rather than silently dropping it. Remove the Unavailable MCP server tag and retry; clearing the picker explicitly selects no servers. API callers can pass mcpServerIds: [] for the same behavior, or omit mcpServerIds to inherit. The create response reports skipped defaults as mcp_defaults_skipped (a count, without server identities); this is a response warning, not persisted session state.

Deleted servers can remain in saved branch/user default lists. Review those settings to remove stale entries. Agor does not automatically prune these JSON lists: pruning the last branch entry would change the list to empty and thereby activate user-default inheritance. Creation-time handling also covers existing stale lists and a server deleted while a session is being created.

Reading the server list

Settings shows transport and scope below each server name, with separate columns for ownership, configured Enabled/Disabled state, and authentication/discovered capabilities. Shared means no private owner; it does not identify who added the server. View details shows creation/update timestamps. Creator and last-modifier identities are not recorded, so ownership must not be interpreted as an audit trail.

Not signed in needs authentication. A discovered tool count is saved capability information, not a live connectivity check; use the editor’s connection test when checking reachability.

Catalog visibility

The Catalog shows servers available for new connections. Hidden entries cannot be found or installed through Catalog. Hiding an entry does not revoke an existing connection: manage saved servers and reconnect through My Servers. Existing authentication and access checks still apply.

Catalog availability can change between releases, including when a provider requires client approval that Agor cannot complete. A listed entry is not a guarantee that every provider account can connect; follow the readiness guidance and provider requirements shown before connecting.

Deleting a saved server

In My Servers → Settings → Remove server, the confirmation shows the total number of sessions still attached, including disabled attachments. Choose Delete and detach to remove the server, its saved connection, and those attachments together (or Delete when none are attached). Cancel changes nothing. If the attachment count changes before deletion, review the refreshed count and confirm again. Counts do not reveal names or details of sessions you cannot view.

Future turns no longer resolve the deleted server. The existing runtime revocation mechanism interrupts mediated tool access where enabled; deletion cannot recall credentials already handed to a direct, unmediated running agent. Saved branch/user defaults remain unchanged, as described above.

The session picker offers only shared servers and private servers usable by both you and the session owner. Administrative inventory remains separate. Already attached servers retain their names when those details are readable, including while choices refresh or when you cannot change the attachments. Displaying an attached name does not make that server available to attach again.

Authentication

Private and shared installations

Catalog defaults to Private, including for administrators. Administrators and members allowed to create shared servers can explicitly choose Shared. This shares the configuration, not the installer’s account: Catalog supports shared open servers and per-user OAuth only. Each user signs in separately. Bearer/API keys and other embedded credentials remain private. The live endpoint’s auth requirement, not just the catalog label, is checked before installation.

Both choices are session-scoped: a shared install is available to attach, not automatically enabled in every session. Settings’ ownership choice is independent of scope. Settings → MCP Servers also defaults new configurations to Private. Private + Global applies only to the owner’s sessions, not every user’s sessions. This UI default does not change historical admin CLI/MCP/API creation defaults when ownership is omitted. Manual shared configurations can share embedded credentials; only per-user OAuth or user environment references isolate user credentials. Existing ownership cannot be changed by editing a server.

Catalog reconnect selects the requested ownership identity; Private never falls back to a shared row or someone else’s private configuration. A matching shared install is reused without changing configuration. Disabled or changed shared installs require an explicit Settings action rather than automatic reconciliation. Cancelling sign-in or a failed Connect response does not remove a shared install: another user may already have adopted it. Remove it explicitly in My Servers or Settings. Private installs retain owner-specific reconciliation and credential rotation fencing. OAuth reconnect always acts on the signing-in user’s grant; it never copies another user’s grant or falls back to a shared OAuth credential.

Members restricted to existing servers (or to creating private servers) can explicitly choose Use existing shared when Catalog finds an eligible shared installation. This does not publish, repair, or re-enable configuration; members can sign in with their own per-user OAuth grant. Private remains a separate choice and never silently selects shared configuration. Members restricted to existing servers can also reuse their matching private installations. Advisory readiness does not grant permission to create or repair a server; the daemon checks again.

Catalog’s pre-connect readiness is advisory from catalog and saved-connection data; it does not probe the endpoint. Agor checks the live endpoint only when you choose Connect and before installing it. An entry may be:

Open: Agor adds the server to My Servers. From the inline next step, choose Start new session to select a teammate and agent tool, or keep browsing.
OAuth: Agor adds the server and pre-opens the provider sign-in window. The Catalog drawer remains at Sign-in pending until the durable per-user grant is confirmed; My Servers remains the recovery path if sign-in is not completed.
Bearer token: Catalog accepts this only when the checked-in catalog explicitly prescribes the reviewed bearer scheme. The token is verified against the catalog endpoint before storage. A generic 401 or 403 is not proof that a bearer token will work. A provider may advertise OAuth and separately document bearer tokens; that route is allowed only through the entry’s explicit oauth_challenge_compatible: true review flag (GitHub is the current example), never inferred from the challenge.
Unknown: Agor checks the endpoint at connect time. If it has changed to OAuth or open access, the drawer updates. An unreviewed custom-header, Basic, multi-key, or signed scheme is refused.

For unsupported schemes, configure the server in Settings → MCP Servers. Custom headers still support alternatives such as Datadog API/application-key pairs; Catalog’s Datadog entry uses Datadog’s recommended browser OAuth flow instead of asking users to manage a long-lived PAT or SAT. That card targets Datadog’s US1 MCP endpoint. Other Datadog sites need their regional endpoint configured manually, and an organisation may need to allow-list the Agor callback under MCP OAuth Redirect URLs before sign-in completes.

Datadog now uses its documented US1 endpoint , https://mcp.datadoghq.com/v1/mcp, without additional toolsets or permissions. Saved rows are not automatically migrated from /api/unstable/mcp-server/mcp. Those rows no longer match the current catalog: absent an explicit compatibility override, they fall back to strict OAuth, which invalidates grants bound to the former marketplace policy. Explicit Catalog Connect can reconcile the caller’s owned row to the new endpoint through the existing flow; old-resource grants are not reusable there, so renewed authorization is required.

Inspecting OAuth policy and failures

The saved-server editor shows Saved OAuth policy from the daemon, independently of unsaved form values. Ordinary GET /mcp-servers and GET /mcp-servers/:id reads include oauth_compatibility_policy: effective_mode, managed_by_catalog, effective_dcr_mode, and dcr_mode_source (explicit or default). Omitted DCR mode still means advertised; an explicit disabled choice remains disabled. Marketplace compatibility still requires a canonical install of the current catalog entry.

Save responses and realtime replacements do not include this projection. The editor reads the saved revision again without changing your draft. Until that read succeeds, it shows loading or unavailable rather than the previous revision’s policy. Retry policy read repeats only the read; it does not repeat the save, OAuth flow, or connection test.

When Start OAuth Flow fails, the existing recovery alert and recovery API object include the policy used by the failed operation (oauth_policy) and a closed failure_reason when known: dcr_disabled, registration_endpoint_missing, protected_resource_mismatch, issuer_mismatch, pkce_required, profile_rejected, or endpoint_override_mismatch. Guidance comes from Agor, not provider response text. Unknown failures remain generic rather than guessing from provider prose. Callback issuer failures also carry a reason; historical attempt status does not reconstruct the policy used by an earlier flow.

Opening the editor or reading saved policy does not discover metadata, register clients, request consent, or change grants. It is not a live provider health check. Starting OAuth and Save & Test Connection remain explicit operations with side effects. No diagnostic action automatically retries a weaker compatibility policy or enables DCR. These reads retain the existing tenant and server-visibility authorization.

Expiring OAuth access and refresh

Connected means the saved access grant is currently usable according to its stored expiry and configuration binding; it is not a live provider health check. Refresh needed means access has expired and a refresh credential is stored. Agor attempts refresh just before use, including Refresh tools and saved-server connection tests, without opening a sign-in window. Inventory reads never contact providers. A successful refresh atomically replaces the access token and any rotated refresh token; an omitted refresh token preserves the old one.

GitLab normally issues access tokens lasting two hours (expires_in: 7200). This is the provider’s access-token lifetime, not an Agor daily sign-in limit. Agor sends the grant’s original redirect URI and client credentials when refreshing. A valid stored refresh grant can renew access without user interaction.

If the token endpoint definitively rejects the grant/client, Agor retires that exact grant. If an exchange may have consumed a rotating refresh token but its result was lost or malformed, Agor quarantines it instead of replaying it. Use Connect or Reconnect in the server’s settings to sign in again. Temporary, unambiguous provider rejections preserve the grant for retry; a missing refresh token or incompatible saved client may also require sign-in.

Existing bound grants with valid refresh credentials can recover on their next use after an upgrade. A missing original redirect/client, revoked grant, or quarantined/lost rotation may need one new sign-in. Upgrading cannot recover a token pair the provider issued but Agor never received. Do not disconnect a working refreshable grant merely because access expired.

Saved client-credentials configurations

Client credentials (machine-to-machine OAuth) and browser authorization-code grants are not interchangeable. Test Authentication and direct standalone core integrations retain their legacy client-credentials exchange, but it does not persist a browser grant or establish that a saved server is usable for tasks. Daemon-backed execution and HA discovery require a bound durable OAuth grant. Saved standalone discovery now follows the same boundary rather than minting an untracked machine token. This is a compatibility change for installations that previously used standalone Refresh tools with client credentials alone.

When no durable grant exists for a client-credentials configuration, discovery reports Review configuration, not browser reauthentication. Configure authorization-code OAuth if the provider supports it, or use a provider-supported bearer credential. A machine-only provider cannot be repaired by repeatedly opening browser sign-in. Configured client IDs and secrets can also belong to browser OAuth; an existing bound grant continues to work regardless of the legacy form’s grant-type default. Agor never falls back to machine-token minting after a browser grant fails or is retired.

A newer refresh on another daemon may temporarily require retrying a request; it does not require replacing a healthy grant. For rotating credentials, even a crash after the durable dispatch fence but before network dispatch can require one sign-in: Agor cannot safely prove that the provider did not consume the token and will not replay it.

Recovering a provider-deleted OAuth client (administrators)

If reconnect repeatedly reports an unknown or deleted OAuth client, ask your workspace administrator to follow the client recovery procedure. An administrative reset affects every user’s saved grant for that server; it is not a routine reconnect and does not revoke tokens at the provider.

Saved OAuth status

OAuth badges reflect the last saved-grant check, refreshed when the UI loads or reconnects and after explicit OAuth actions/events. Idle tabs do not scan all grants on a timer. The badge is not a live provider-health guarantee: credentials can expire or be revoked between observations. Runtime credential resolution independently validates the effective session servers (attached and enabled global servers), and refreshes credentials when needed. A provider timeout is not proof that authentication has been revoked.

Capability metadata

Remote tool, resource, and prompt descriptions are untrusted optional free text. Agor keeps every valid capability name and schema, but deterministically shortens descriptions that exceed the per-field or aggregate safe metadata budget. Test Connection (or Save & Test Connection for a saved/OAuth server) reports when this happened. Malformed names, schemas, or non-string descriptions still fail validation instead of being silently repaired. The same bounded tool descriptions are stored for display and applied by the mediated MCP egress path used in compatibility and enforced gateway modes.

For Google MCP servers, Agor requests offline access and explicit consent so Google can issue a refresh token. Once connected, an expired access token is renewed from that durable grant before use; an authenticated provider 401 receives one forced refresh and retry when the daemon egress gateway owns the request. Google commonly omits refresh_token from refresh responses, so Agor preserves the previously stored value. Reconnect only when Google permanently rejects or revokes the grant (for example, invalid_grant); a temporary provider or network failure does not discard it.

Local stdio servers

An stdio configuration uses only its command, arguments, and environment. HTTP/SSE authentication, URL, and custom-header fields do not apply. Agor does not download the command: it must already be available in the actual executor environment, which may differ from the daemon host. Store a per-user token in Settings → Environment Variables, then reference it from the server environment, for example {"SHORTCUT_API_TOKEN":"{{ user.env.SHORTCUT_API_TOKEN }}"}. The managed value is encrypted and resolved only for the authenticated user whose task is running; do not paste the token directly into the MCP server definition.

Upgrading Agor removes obsolete remote-auth, URL, and header fields from existing stdio rows while preserving their command, arguments, environment, ownership, and session attachments. It also deletes OAuth grants and pending OAuth attempts that cannot apply to an stdio process; credentials for remote servers are unchanged. Editing an stdio server performs the same repair. This keeps strict transport validation in place rather than allowing mixed local/remote configurations at runtime. If you later switch that server to remote OAuth, sign in again.

Safe edits, storage, and removal

Bearer tokens and other MCP auth/header/env secrets are stored in MCP server JSON according to the deployment’s storage security. Catalog installs carrying bearer credentials are private to their owner, access controls restrict the row, and API, realtime, and UI projections redact secrets. Redaction is an output-boundary control, not application-level encryption; encryption at rest applies only when the deployment’s documented database or storage configuration guarantees it. OAuth access and refresh tokens use Agor’s durable per-user OAuth token store; PostgreSQL deployments envelope-encrypt those token fields. Token and client-secret values are not returned by status endpoints or written to operational logs.

Test Authentication on a new form checks authentication setup; Test Connection lists capabilities. Saved servers and new OAuth servers use Save & Test Connection: it saves the current form first, then probes only that durable server configuration. This preserves saved secrets and binds OAuth grants to the correct endpoint. A failed save prevents the probe. After OAuth creates a server, Save saves subsequent edits rather than simply dismissing the form. Results are cleared when the draft, server, or authenticated caller changes.

Editing authentication is patch-safe: leaving a saved secret blank preserves it, while Clear saved secret explicitly removes it. Other omitted authentication fields are preserved; switching authentication type replaces the old mode. The edit form uses a configuration revision to detect another device’s concurrent save. If that happens, Reload latest fetches the authoritative row and deliberately discards the local unsaved form before another save. OAuth shared/per-user mode changes remove credentials and grants that belong to the previous subject mode.

Connecting an entry again reuses the same installation for the selected ownership; starting a session is a separate, explicit action. Supplying a new bearer token verifies and atomically rotates that stored install; the previous token is not retained in another catalog row. Remove the MCP server in Settings → MCP Servers to delete Agor’s stored configuration and token.

Connection restrictions and recovery

Your workspace’s MCP security mode can restrict which servers are available. In off and observe, agents connect directly and receive reusable credentials; editing or removing a saved connection is not a synchronous revocation boundary for an already-running agent.

In compatibility and enforced, eligible bounded Streamable HTTP connections go through the daemon instead. Reusable provider credentials stay in the daemon; the agent receives access scoped to its current task and authorized user, tenant, session, and server. This access stops working when the task is no longer live.

These mediated modes do not support stdio, legacy SSE endpoint handoff, WebSocket, unbounded streaming, or servers requiring ask approval. Unsupported connections are omitted or fail closed, including on remote executors; they do not silently fall back to direct credentials. Some environment templates are also unsupported. If a required server disappears, ask an administrator to check connection diagnostics and mode restrictions.

After a connection, credential, attachment, or permission change:

Claude: Reconnect MCP can refresh the connections without restarting the conversation. Tool visibility changes that require a new turn still wait for that turn. An uncertain reconnect timeout blocks further live replacement for the current turn.
Other integrations and historical Claude CLI sessions: changes apply on the next turn, not midway through the current one.
Sign-in required: replaced or disconnected OAuth grants may need fresh authorization. Routine access-token refresh does not require reconnecting.

Live recovery applies only in compatibility and enforced; direct modes apply configuration changes on the next turn. An excluded server does not prevent other eligible connections from recovering.

Agor does not replay a failed provider tool call automatically. If dispatch was uncertain, check the external system before asking the agent to repeat an action: it may already have happened. In mediated modes, no new request hop is admitted after a relevant change commits, but an already-admitted request may complete. Disconnecting retires Agor’s local grant; it does not revoke the grant at the provider.

Only connect providers you trust. The gateway filters accidental credential reflection in bounded responses, but cannot stop a malicious provider from encoding or exfiltrating a credential it legitimately received. Filtering does not cover every short or low-complexity value.

A tenant-shared OAuth grant records the authenticated user who established it, independently of the MCP server’s owner. Routine token refresh keeps that attribution. When another currently authorized administrator completes new consent, the token and its attribution are replaced together.

Hard-deleting the consenting account retires its locally stored shared grant as well as its personal grants. A current administrator must authorize the shared server again. Deleting a former consenter does not remove a newer grant established by someone else. This policy concerns hard deletion, not a role change, and does not transfer consent to the server owner.

Retirement deletes Agor’s stored access/refresh tokens and grant-bound client material. Agor makes no provider revocation request, synchronously or asynchronously; use the provider’s security settings if revocation is required. Already-admitted mediated requests may finish; new mediated hops and fresh authentication-status reads no longer accept the removed grant. Direct provider connections in off or observe mode remain subject to the provider’s own lifetime/revocation rules.

Browser callbacks and manual OAuth completion use the trusted initiating user, not request fields. The client-credentials Test Authentication path is a request-local probe: it neither establishes/replaces a durable shared grant nor retains its token in a process cache. Saved client configuration is distinct from a stored grant; a successful probe alone is not durable shared authorization.

Upgrade: shared-grant attribution (`0105`, both databases)

This upgrade removes historical shared grants and requires new administrator consent. Per-user grants are preserved. Operators must follow the offline migration and rollback instructions before upgrading; do not run old and new daemons against the upgraded schema.

Catalog curation for operators

To propose or maintain catalog entries, see Contributing to the MCP catalog. Hiding an entry prevents new catalog installs, but does not revoke existing connections.