elastic · shainaraskas · Jun 24, 2026
@@ -559,6 +559,7 @@ toc:
             children:
               - file: users-roles/cloud-organization/register-elastic-cloud-saml-in-okta.md
               - file: users-roles/cloud-organization/register-elastic-cloud-saml-in-microsoft-entra-id.md
+          - file: users-roles/cloud-organization/manage-mcp-client-connections.md
       - file: users-roles/cloud-enterprise-orchestrator.md
         children:
           - file: users-roles/cloud-enterprise-orchestrator/manage-system-passwords.md

@@ -0,0 +1,120 @@
+---
+navigation_title: "Application connections"
+description: "Audit and revoke MCP client connections across an Elastic Cloud organization's serverless projects from a single organization-level view."
+type: how-to
+applies_to:
+  serverless: preview
+products:
+  - id: cloud-serverless
+---
+
+# Manage MCP client connections [manage-mcp-client-connections]
+
+The **Application connections** page in the Elastic Cloud Console gives organization administrators a single place to audit and revoke [MCP client](/explore-analyze/ai-features/agent-builder/mcp-client-oauth.md) connections that members of your organization have authorized across their {{serverless-short}} projects.
+
+:::{note}
+During technical preview, application connections cover **MCP clients only**, and connected applications get **read-only** access through Elasticsearch Query Language (ES|QL)-based tools. Support is limited to {{serverless-short}} projects.
+:::
+
+To create an MCP client or connect an MCP host such as **Claude Desktop**, see [Connect an MCP host to an MCP client](/explore-analyze/ai-features/agent-builder/mcp-client-connect.md) in the Agent Builder documentation. This page covers organization-level management only.
+
+## Before you begin [manage-mcp-client-connections-before-you-begin]
+
+To access this page, open **Organization → Security settings → Application connections** in the Elastic Cloud Console. What you can see and revoke depends on your role:
+
+* **Organization owners** see every application connection in the organization.
+* **Other users** see connections for the projects they administer, plus any connections they authorized themselves.
+
+<!-- TODO: confirm exact Cloud role names (e.g. "Organization owner") against the final RBAC copy. Source: Lloyd Chan / Simona. -->
+<!-- Authoritative per AS TDD (Jake, v1.0): org owner sees all org connections; a normal user sees
+     connections for projects they administer + connections directly their own; grouped by client_id. -->
+
+The page offers two views, toggled by the **Group by client** and **List view** buttons:
+
+* **Group by client** (default for organization owners) — lists each MCP client with a count of its connections. Expand a client row to see individual connections.
+* **List view** — shows all connections in a flat, sortable table.
+
+## View application connections
+
+The **Application connections** page shows each MCP client and its connections. In grouped view, expand a client to see its individual connections. Each connection row shows the following details:
+
+| Column | Description |
+| --- | --- |
+| Connection name | The name of the connection, derived from the MCP client name. |
+| Authorization date | When the user authorized the connection. |
+| Connected by | The email address of the user who authorized the connection. |
+| Status | The current state of the connection. See [Connection statuses](#connection-statuses). |
+
+<!-- TODO: confirm behavior when the user is no longer an org member — code review (lib.ts) shows email is
+     tried first (memberEmail), with a fallback to raw user_id. Email display confirmed from QA screenshot
+     (June 23 2026). Source: Dennis Tismenko. -->
+
+:::{note}
+This page shows all MCP clients for your organization, including clients created through the {{kib}} API using an {{ecloud}} API key. Those clients are not visible in the Agent Builder client list in {{kib}} — the organization-level view here is the only place to manage them.
+:::
+
+To narrow the list, use the search box to filter by name, or use the **Status** filter.
+
+If no project in your organization has any MCP client connections yet, the page shows an empty state. Open a {{serverless-short}} project to begin. Connections appear here once users start authorizing MCP clients.
+
+### Connection statuses
+
+A connection has one of the following statuses:
+
+* **Active** — the connection is authorized. The session may have expired if unused for 30 or more days.
+* **Expired** — the connection's refresh window lapsed after 30 days of inactivity. The user must re-authorize to use it again.
+* **Revoked** — the connection was revoked and can no longer be used.
+
+<!-- Statuses per Jake (Apr 9) + PRD. Expiry is lazy/inactivity-based (30-day refresh window per AS TDD). -->
+
+<!-- TODO: confirm retention windows for tech preview. -->
+Revoked connections remain visible for 3 months and revoked clients for 1 year (use the status filter to show them). Expired connections remain visible until re-authorized or removed.
+
+## View MCP client details
+
+Select a client to open its details panel. The panel shows the connection details a user needs to configure an MCP host, for reference:
+
+* **Client ID** — the unique identifier for the MCP client.
+* **MCP server URLs** — the redirect URIs configured for this client (the callback URLs used during the OAuth consent flow).
+* A reminder that the **client secret** is required for confidential clients and is shown only once, when the client is created.
+
+<!-- TODO: the "MCP server URLs" field in the Cloud Console flyout renders client.redirect_uris, not the
+     MCP server endpoint. The tooltip says "Elastic MCP server endpoint" but the actual data is redirect URIs.
+     Confirm with Simona/Dennis whether this is intentional before publish — it may be a labeling issue. -->
+<!-- Do NOT hardcode the MCP server URL / AS URL in examples — format is changing per cp-iam #2957. -->
+
+To create or edit a client, click **Manage MCP client** to open the project's Agent Builder client management in Kibana.
+
+<!-- TODO: confirm "Manage MCP client" button target (Kibana Agent Builder → Manage MCP Clients) and whether to
+     cross-link or describe. Source: Dennis Tismenko. -->
+
+## Revoke connections
+
+Revoking removes the selected connections only. The MCP client stays registered and can accept new connections, and an application can be reconnected at any time.
+
+To revoke a single connection, click **Revoke** in its row.
+
+To revoke several connections at once:
+
+1. Select the checkbox for each connection you want to revoke. In grouped view, use **Select all connections for this client** to select every connection under a client, or **Clear selection** to start over.
+2. Click **Revoke *N* connections**.
+3. Review the connections in the confirmation dialog, then click **Revoke access**.
+
+You can revoke up to 100 connections at a time.
+
+:::{tip}
+Removing a user from your identity provider does **not** automatically revoke that user's connections. When a user leaves, revoke their connections here to cut off access.
+:::
+
+To revoke an entire MCP client and all its connections, the client's creator removes it from the project's Agent Builder client management in Kibana. See [Revoke an MCP client or connection](/explore-analyze/ai-features/agent-builder/mcp-client-revoke.md).
+
+## Next steps
+
+- To restore access after revoking a client, [create a new MCP client](/explore-analyze/ai-features/agent-builder/mcp-client-create.md) and distribute the credentials to users.
+
+## Related pages
+
+* [Create an MCP client](/explore-analyze/ai-features/agent-builder/mcp-client-create.md) (Agent Builder)
+* [Connect an MCP host to an MCP client](/explore-analyze/ai-features/agent-builder/mcp-client-connect.md) (Agent Builder)
+* [Revoke an MCP client or connection](/explore-analyze/ai-features/agent-builder/mcp-client-revoke.md) (Agent Builder)
+* [Authenticate MCP clients with OAuth](/explore-analyze/ai-features/agent-builder/mcp-client-oauth.md)
@@ -0,0 +1,162 @@
+---
+navigation_title: "Connect an MCP host"
+description: "Configure an MCP host to use an OAuth MCP client and complete the user consent flow to establish a connection to Agent Builder."
+type: how-to
+applies_to:
+  serverless: preview
+products:
+  - id: elasticsearch
+  - id: kibana
+  - id: observability
+  - id: security
+  - id: cloud-serverless
+---
+
+# Connect an MCP host to an MCP client [mcp-client-connect]
+
+After [creating an MCP client](mcp-client-create.md), configure your MCP host with the client ID and MCP server URL, then complete the OAuth consent flow to establish the connection.
+
+This page covers two common MCP hosts: the **Claude Code CLI** (which has native OAuth support) and **Claude Desktop** (which uses the `mcp-remote` adapter). Other hosts that support OAuth 2.1 with PKCE follow the same general pattern — consult your host's documentation for the specific configuration format.
+
+## Before you begin [mcp-client-connect-before-you-begin]
+
+- You have a client ID and MCP server URL from [creating an MCP client](mcp-client-create.md).
+- You have access to the {{serverless-short}} project that the MCP client is scoped to.
+
+## Step 1: Configure your MCP host
+
+Choose the instructions for your host.
+
+### Claude Code CLI
+
+**Option 1: Native HTTP transport (recommended)**
+
+The Claude Code CLI supports OAuth natively — no additional adapter is required. When you created the client, the redirect URI `http://localhost:3000/callback` should be in your redirect URI list.
+
+Run the following command, replacing `{CLIENT_ID}` and `{MCP_SERVER_URL}` with the values from your client's details page in {{kib}}:
+
+```bash
+claude mcp add --transport http --client-id {CLIENT_ID} kibana-mcp {MCP_SERVER_URL}
+```
+
+:::{note}
+Confidential clients also require `--client-secret {CLIENT_SECRET}` in the preceding command.
+
+<!-- TODO: confirm `--client-secret` flag name for confidential clients in Claude Code CLI.
+     Source: Jake Landis (back from PTO 2026-07-06). -->
+:::
+
+**Option 2: mcp-remote adapter**
+
+Use this option if your version of Claude Code doesn't support native HTTP OAuth transport. When you created the client, the redirect URI `http://localhost:3000/oauth/callback` should be in your redirect URI list.
+
+```bash
+claude mcp add --transport stdio kibana-mcp -- \
+  npx mcp-remote \
+  "{MCP_SERVER_URL}" \
+  --static-oauth-client-info \
+  "{\"client_id\":\"{CLIENT_ID}\"}"
+```
+
+Replace `{MCP_SERVER_URL}` and `{CLIENT_ID}` with the values from your client's details page in {{kib}}.
+
+:::{note}
+Confidential clients must include the client secret in the `--static-oauth-client-info` JSON: `{"client_id":"{CLIENT_ID}","client_secret":"{CLIENT_SECRET}"}`.
+:::
+
+<!-- TODO (Jake Landis, back 2026-07-06): confirm whether Option 2 (mcp-remote + stdio) should
+     be kept in public docs for tech preview users, or whether all preview-era Claude Code CLI
+     builds support native HTTP OAuth and Option 2 can be removed. Both options appear in
+     cp-iam-team#2963 testing notes (June 18) as equally valid QA paths; Elena Shostak confirmed
+     --transport http working in #cp-iam-oauth-project June 5 + June 18. Jake to advise on
+     public-facing guidance. -->
+
+The server is now configured. Start a Claude Code session — the OAuth consent flow triggers automatically on the first use of the server.
+
+### Claude Desktop
+
+Claude Desktop uses the [mcp-remote](https://www.npmjs.com/package/mcp-remote) adapter to handle OAuth connections. When you created the client, the redirect URI `http://localhost:3000/oauth/callback` should be in your client's redirect URI list.
+
+1. In Claude Desktop, open **Settings → Developer → Edit Config**. This opens `claude_desktop_config.json` in your text editor.
+2. Add your MCP client to the `mcpServers` object:
+
+   ```json
+   {
+     "mcpServers": {
+       "kibana-mcp": {
+         "command": "npx",
+         "args": [
+           "mcp-remote",
+           "{MCP_SERVER_URL}",
+           "--static-oauth-client-info",
+           "{\"client_id\":\"{CLIENT_ID}\"}"
+         ]
+       }
+     }
+   }
+   ```
+
+   Replace `{MCP_SERVER_URL}` and `{CLIENT_ID}` with the values from your client's details page in {{kib}}.
+
+   :::{note}
+   Confidential clients also require a `client_secret` in the `--static-oauth-client-info` JSON. Include it as `"client_secret":"{CLIENT_SECRET}"` alongside the `client_id`.
+   :::
+
+3. Save the file and restart Claude Desktop to load the new configuration.
+
+**Other MCP hosts** — most hosts that support OAuth 2.1 with PKCE accept a similar configuration. Provide the `{MCP_SERVER_URL}` and `{CLIENT_ID}` in the format your host requires.
+
+## Step 2: Authorize the connection
+
+The first time your MCP host tries to use the configured server, it opens a browser window and starts the OAuth consent flow.
+
+1. Your browser opens to an {{ecloud}} sign-in page. Sign in with your {{ecloud}} credentials, even if you already have an active session — authentication is always required before you can grant consent.
+2. The **Connect and authorize** page opens, showing which project the MCP client is requesting access to. Click **Authorize** to grant access.
+3. The browser confirms the authorization is complete. Close the tab and return to your MCP host.
+
+A new **app connection** is created in {{kib}}, scoped to your account and the project the MCP client was registered for. The connection name is auto-generated in the format `<client-name>#<word-pair>`.
+
+:::{note}
+If you click **Deny**, no connection is created. The host retries the flow the next time you use a tool, or you can restart the host to trigger a fresh attempt.
+:::
+
+## Verify the connection
+
+In {{kib}}, go to **Agent Builder → Tools library**, click **Manage MCP**, and select **Manage MCP clients (OAuth)** to confirm the connection count for your client has increased. If you don't see it within a minute of authorizing, refresh the page.
+
+You can also check your connection in the Cloud Console at **Organization → Security settings → Application connections**.
+
+## Troubleshoot
+
+**The host shows an error and doesn't open a browser.**
+
+Confirm the `{MCP_SERVER_URL}` in your config matches exactly what {{kib}} displays. The correct URL ends with `/api/agent_builder/mcp`. A typo, extra slash, or doubled path segment will prevent the OAuth discovery step from completing.
+
+**Authorization completed but no connection appears in {{kib}}.**
+
+Confirm you have access to the {{serverless-short}} project the client was registered for. If your account doesn't have project access, the consent step fails silently.
+
+**The host shows a new sign-in prompt after a period of inactivity.**
+
+Connections expire after 30 days without use. Complete the authorization flow again to re-establish the connection.
+
+**The authorization flow fails after you wait on the consent page.**
+
+The MCP host's local callback server times out if the **Connect and authorize** page is left open too long before you click **Authorize**. Start the flow again and click **Authorize** promptly without leaving the consent page open.
+
+**You need to start fresh with a new connection.**
+
+Consult your MCP host's documentation for how to clear cached OAuth credentials and force a new authorization. Most hosts maintain only one connection per MCP server URL, so reconfiguring with the same URL will reuse the existing connection unless the cached credentials are cleared.
+
+<!-- Guardrail: do NOT include ~/.mcp-auth rm, NODE_TLS_REJECT_UNAUTHORIZED=0,
+     or any QA-environment-specific credential-clearing commands. -->
+
+## Next steps
+
+- [Revoke an MCP client or connection](mcp-client-revoke.md) when access is no longer needed.
+
+## Related pages
+
+- [Authenticate MCP clients with OAuth](mcp-client-oauth.md)
+- [Create an MCP client](mcp-client-create.md)
+- [Manage application connections](/deploy-manage/users-roles/cloud-organization/manage-mcp-client-connections.md)