|
| 1 | +--- |
| 2 | +navigation_title: "Connect an MCP host" |
| 3 | +description: "Configure an MCP host to use an OAuth client and complete the authorization flow to establish a connection to Agent Builder." |
| 4 | +type: how-to |
| 5 | +applies_to: |
| 6 | + serverless: preview |
| 7 | +products: |
| 8 | + - id: elasticsearch |
| 9 | + - id: kibana |
| 10 | + - id: cloud-serverless |
| 11 | +--- |
| 12 | + |
| 13 | +# Connect an MCP host to {{agent-builder}} |
| 14 | + |
| 15 | +After an OAuth client is [created](create-oauth-client.md), configure your MCP host, usually your AI agent, with the client ID and MCP server URL, then complete the OAuth authorization flow to establish the connection. After completing the setup, your MCP host has an authorized OAuth connection to {{agent-builder}} and can run its tools with your permissions. |
| 16 | + |
| 17 | +This page covers two common MCP hosts: |
| 18 | +* Claude Code CLI, which has native OAuth support |
| 19 | +* Claude Desktop, which uses the `mcp-remote` adapter |
| 20 | + |
| 21 | +Other OAuth 2.1 hosts follow the same general pattern, so consult your host's documentation for the specific configuration format. |
| 22 | + |
| 23 | +## Before you begin [connect-mcp-host-before-you-begin] |
| 24 | + |
| 25 | +Confirm the following before you configure your MCP host: |
| 26 | + |
| 27 | +- You have an MCP host that supports OAuth 2.1, such as the Claude Code CLI or Claude Desktop. |
| 28 | +- You have the client ID and MCP server URL for the OAuth client. You either [created the client](create-oauth-client.md) yourself or received these values from the person who did. |
| 29 | +- You have access to the {{serverless-short}} project that the OAuth client is scoped to, not just organization-level access. The connection acts with your own permissions in that project, so you also need the privileges required for the tools you'll run through the MCP server, such as {{agent-builder}} access and **Read** access to any data those tools query. To learn more, refer to [Permissions](/explore-analyze/ai-features/agent-builder/permissions.md). |
| 30 | + |
| 31 | +## Connect your MCP host to an OAuth client [connect-mcp-host] |
| 32 | + |
| 33 | +Complete the following steps to start using your OAuth client in your MCP host. |
| 34 | + |
| 35 | +:::::::{stepper} |
| 36 | + |
| 37 | +::::::{step} Configure your MCP host |
| 38 | + |
| 39 | +Choose the instructions for your host. |
| 40 | + |
| 41 | +:::::{tab-set} |
| 42 | + |
| 43 | +::::{tab-item} Claude Code CLI |
| 44 | + |
| 45 | +**Option 1: Native HTTP transport (recommended)** |
| 46 | + |
| 47 | +The Claude Code CLI supports OAuth natively, so no additional adapter is required. |
| 48 | + |
| 49 | +Run the following command, replacing `{CLIENT_ID}` and `{MCP_SERVER_URL}` with the values for your OAuth client: |
| 50 | + |
| 51 | +```bash |
| 52 | +claude mcp add --transport http --client-id {CLIENT_ID} kibana-mcp {MCP_SERVER_URL} |
| 53 | +``` |
| 54 | + |
| 55 | +:::{note} |
| 56 | +For a confidential client, add the `--client-secret` flag. The flag takes no value: the CLI prompts for the secret with masked input. To skip the prompt, set the `MCP_CLIENT_SECRET` environment variable before you run the command. |
| 57 | + |
| 58 | +```bash |
| 59 | +claude mcp add --transport http --client-id {CLIENT_ID} --client-secret kibana-mcp {MCP_SERVER_URL} |
| 60 | +``` |
| 61 | +::: |
| 62 | + |
| 63 | +When Claude Code starts the OAuth flow, it listens for the authorization response at `http://localhost/callback`. This is one of the default redirect URIs populated in the [OAuth client registration form](/deploy-manage/app-connections/create-oauth-client.md#create-the-client), so it should be included in your client's redirect URIs unless you explicitly removed it. |
| 64 | + |
| 65 | +**Option 2: mcp-remote adapter** |
| 66 | + |
| 67 | +Use this option if your version of Claude Code doesn't support native HTTP OAuth transport. |
| 68 | + |
| 69 | +```bash |
| 70 | +claude mcp add --transport stdio kibana-mcp -- \ |
| 71 | + npx mcp-remote \ |
| 72 | + "{MCP_SERVER_URL}" \ |
| 73 | + --static-oauth-client-info \ |
| 74 | + "{\"client_id\":\"{CLIENT_ID}\"}" |
| 75 | +``` |
| 76 | + |
| 77 | +Replace `{MCP_SERVER_URL}` and `{CLIENT_ID}` with the values for your OAuth client. |
| 78 | + |
| 79 | +:::{note} |
| 80 | +Confidential clients must include the client secret in the `--static-oauth-client-info` JSON: `{"client_id":"{CLIENT_ID}","client_secret":"{CLIENT_SECRET}"}`. |
| 81 | +::: |
| 82 | + |
| 83 | +When the `mcp-remote` adapter starts the OAuth flow, it listens for the authorization response at `http://localhost/oauth/callback`. This is one of the default redirect URIs populated in the [MCP client registration form](/deploy-manage/app-connections/create-oauth-client.md#create-the-client), so it should be included in your client's redirect URIs unless you explicitly removed it. |
| 84 | + |
| 85 | +The server is now configured. Start a Claude Code session. The OAuth authorization flow triggers automatically on the first use of the server. |
| 86 | + |
| 87 | +:::: |
| 88 | + |
| 89 | +::::{tab-item} Claude Desktop |
| 90 | + |
| 91 | +Claude Desktop uses the [mcp-remote](https://www.npmjs.com/package/mcp-remote) adapter to handle OAuth connections. |
| 92 | + |
| 93 | +To configure Claude Desktop: |
| 94 | + |
| 95 | +1. In Claude Desktop, open **Settings → Developer → Edit Config**. This opens `claude_desktop_config.json` in your text editor. |
| 96 | +2. Add your MCP client to the `mcpServers` object: |
| 97 | + |
| 98 | + ```json |
| 99 | + { |
| 100 | + "mcpServers": { |
| 101 | + "kibana-mcp": { |
| 102 | + "command": "npx", |
| 103 | + "args": [ |
| 104 | + "mcp-remote", |
| 105 | + "{MCP_SERVER_URL}", |
| 106 | + "--static-oauth-client-info", |
| 107 | + "{\"client_id\":\"{CLIENT_ID}\"}" |
| 108 | + ] |
| 109 | + } |
| 110 | + } |
| 111 | + } |
| 112 | + ``` |
| 113 | + |
| 114 | + Replace `{MCP_SERVER_URL}` and `{CLIENT_ID}` with the values for your OAuth client. |
| 115 | + |
| 116 | + :::{note} |
| 117 | + Confidential clients also require a `client_secret` in the `--static-oauth-client-info` JSON: `{"client_id":"{CLIENT_ID}","client_secret":"{CLIENT_SECRET}"}`. |
| 118 | + ::: |
| 119 | + |
| 120 | +3. Save the file and restart Claude Desktop to load the new configuration. |
| 121 | + |
| 122 | +When the `mcp-remote` adapter starts the OAuth flow, it listens for the authorization response at `http://localhost/oauth/callback`. This is one of the default redirect URIs populated in the [OAuth client registration form](/deploy-manage/app-connections/create-oauth-client.md#create-the-client), so it should be included in your client's redirect URIs unless you explicitly removed it. |
| 123 | + |
| 124 | +:::: |
| 125 | + |
| 126 | +::::{tab-item} Other |
| 127 | + |
| 128 | +Most hosts that support OAuth 2.1 accept a similar configuration to Claude. Provide the `{MCP_SERVER_URL}` and `{CLIENT_ID}` in the format your host requires. |
| 129 | + |
| 130 | +:::: |
| 131 | + |
| 132 | +::::: |
| 133 | + |
| 134 | +:::::: |
| 135 | + |
| 136 | +::::::{step} Authorize the connection |
| 137 | +:anchor: authorize-connection |
| 138 | + |
| 139 | +The first time your MCP host tries to use the configured server, it opens a browser window and starts the OAuth authorization flow. |
| 140 | + |
| 141 | +:::{note} |
| 142 | +Some tools might require additional manual steps. For example, Claude Code CLI requires that you type `/mcp` or run `claude mcp login <mcp-server-name>` before the browser window opens. |
| 143 | +::: |
| 144 | + |
| 145 | +1. Your browser opens to an {{ecloud}} sign-in page. Sign in with your {{ecloud}} credentials. If you have an active session, you are not prompted to log in again. |
| 146 | +2. The **Connect and authorize** page opens, showing which project the OAuth client is requesting access to. Click **Authorize** to grant access. |
| 147 | +3. The browser confirms the authorization is complete. Close the tab and return to your MCP host. |
| 148 | + |
| 149 | +A new app connection is created scoped to your account and the project associated with the OAuth client. The connection name is auto-generated in the format `<client-name>#<word-pair>`. This connection is visible in both {{kib}} and the {{ecloud}} Console. |
| 150 | + |
| 151 | +If you click **Deny** on the **Connect and authorize** page, then 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. |
| 152 | + |
| 153 | +:::: {admonition} Application permissions |
| 154 | +:::{include} /deploy-manage/_snippets/app-connection-permissions.md |
| 155 | +::: |
| 156 | +:::: |
| 157 | + |
| 158 | +:::::: |
| 159 | + |
| 160 | +::::::{step} Verify the connection |
| 161 | + |
| 162 | +This step is optional. To ensure that the connection is registered in {{kib}}, you can check the number of currently active connections for your client. |
| 163 | + |
| 164 | +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. |
| 165 | + |
| 166 | +You can also check your connection in the {{ecloud}} Console at **Organization** → **Security settings** → **Application connections**. |
| 167 | + |
| 168 | +:::::: |
| 169 | + |
| 170 | +::::::: |
| 171 | + |
| 172 | +## Troubleshoot |
| 173 | + |
| 174 | +**The host shows an error and doesn't open a browser.** |
| 175 | + |
| 176 | +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. |
| 177 | + |
| 178 | +**Authorization completed but no connection appears in {{kib}}.** |
| 179 | + |
| 180 | +Confirm you have access to the {{serverless-short}} project associated with the OAuth client. If your account doesn't have project access, the authorization step fails silently. |
| 181 | + |
| 182 | +**The host shows a new sign-in prompt after a period of inactivity.** |
| 183 | + |
| 184 | +Connections expire after 30 days without use. Complete the authorization flow again to re-establish the connection. |
| 185 | + |
| 186 | +**The authorization flow fails after you wait on the authorization page.** |
| 187 | + |
| 188 | +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 page open. |
| 189 | + |
| 190 | +**You need to start fresh with a new connection.** |
| 191 | + |
| 192 | +Consult your MCP host's documentation for how to clear cached OAuth credentials and force a new authorization. Most hosts maintain only one connection for each MCP server URL, so reconfiguring with the same URL will reuse the existing connection unless the cached credentials are cleared. |
| 193 | + |
| 194 | +## Next steps |
| 195 | + |
| 196 | +When access is no longer needed, [revoke the connection](revoke-oauth-client.md). |
| 197 | + |
| 198 | +## Related pages |
| 199 | + |
| 200 | +- [](oauth-clients.md) |
| 201 | +- [](create-oauth-client.md) |
| 202 | +- [](manage-app-connections.md) |
0 commit comments