> ## Documentation Index
> Fetch the complete documentation index at: https://docs.resolve.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

Resolve AI supports integrations with various MCP servers (both remote-hosted or self-hosted).

## Transport Protocols

Resolve AI supports two MCP remote transport protocols:

* **[Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)**
* **[HTTP with SSE](https://modelcontextprotocol.io/specification/2024-11-05/basic/transports#http-with-sse)**

## MCP Server Requirements

Resolve AI discovers and invokes tools on MCP servers using the standard [MCP tools capability](https://modelcontextprotocol.io/docs/concepts/tools). Your MCP server **must** implement the following two JSON-RPC methods:

### `tools/list` — Tool Discovery

Resolve AI calls `tools/list` to discover which tools the MCP server exposes. This is called when the integration is first connected and periodically thereafter. If `tools/list` fails or returns an empty list, the integration will appear unhealthy and no tools will be available.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}
```

The response must return an array of tool definitions. Resolve AI uses three fields from each tool definition:

* **`name`** (required) — Unique identifier for the tool.
* **`description`** (required) — Human-readable description of what the tool does. Resolve AI injects this into agent prompts to decide which tools to call during an investigation.
* **`inputSchema`** (recommended) — JSON Schema object defining expected parameters. If omitted, defaults to an empty object schema.

Other MCP spec fields (`title`, `outputSchema`, `annotations`) are accepted but not currently used by Resolve AI.

### `tools/call` — Tool Invocation

Resolve AI calls `tools/call` to invoke a specific tool with arguments:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "location": "New York"
    }
  }
}
```

The response must follow the standard MCP [`tools/call` format](https://modelcontextprotocol.io/docs/concepts/tools#calling-tools).

## Hosting for MCP Servers

MCP servers must be remotely hosted to integrate with Resolve AI.

* **Provider Hosting**: Some observability or data source platforms host MCPs and expose a URL to connect to. Examples: Linear MCP, Atlassian MCP. Please note Resolve AI keeps an allowlist of trusted MCP servers to prevent customers from connecting to malicious MCP servers. If an MCP server needs to be added to the allowlist, please reach out to our support team.
* **Self-Hosting**: You can host your own MCP server in your environment and connect it to Resolve AI via the [Resolve Satellite](/resolve-satellite). The server just needs to implement the `tools/list` and `tools/call` methods described above.

## Authentication for MCP Servers

MCP supports different forms of authentication:

| Method     | `authMethod` value | Description                                                                                                                           |
| ---------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Token**  | `token`            | Bearer token authentication. The token is sent as `Authorization: Bearer <token>`.                                                    |
| **OAuth**  | `oauth`            | OAuth 2.0 flow. Only supported for publicly accessible MCP integrations. Create a **service account** for shared organization access. |
| **OIDC**   | `oidc`             | Client credentials with an external OIDC provider (e.g., Microsoft Entra).                                                            |
| **Custom** | `custom`           | Custom header-based authentication. You control the header name and value.                                                            |
| **None**   | `none`             | No authentication.                                                                                                                    |

> **Important**: `authMethod` must be one of these exact values: `token`, `oauth`, `oidc`, `custom`, `none`. If omitted, `authMethod` defaults to `token`.

## Integrating with Resolve AI

### Publicly Accessible MCPs

Log in to Resolve AI and connect from the Integrations page: [https://app.resolve.ai/integrations/mcpIntegration/connect](https://app.resolve.ai/integrations/mcpIntegration/connect)

### Self-Hosted in VPC

Install the [Resolve Satellite](/resolve-satellite), then configure the `mcpIntegration` in the satellite `values.yaml` file.

#### Configuration Reference

```yaml theme={null}
integrations:
  <integration-name>: # Unique name for this integration
    type: mcpIntegration
    create: true
    connection:
      mcpServerUrl: <string> # Required. MCP server URL (e.g. http://mcp-server.internal:8000/sse, http://mcp-server.internal:8000/mcp)
      authMethod: <enum> # One of: token, oidc, custom, none. Default: token
      token: <string> # Required when authMethod is "token". The bearer token value (without "Bearer " prefix)
      toolCallTimeoutMs: <number> # Optional. Timeout for MCP tool calls in ms. Default: 30000, max: 300000
      oidcAuthData: # Required when authMethod is "oidc"
        clientId: <string>
        clientSecret: <string>
        externalOidcProviderUrl: <string> # Token endpoint URL
        externalOidcParameters: # Optional
          microsoftEntraApplicationId: <string> # For Microsoft Entra scope resolution
          scope: <string>
          audience: <string>
      customAuthData: # Required when authMethod is "custom"
        headerName: <string> # HTTP header name (e.g., Authorization, X-API-Key)
        authSchema: <string> # JSONPath to resolve the header value (e.g., $.token)
    secret: # Inline secrets — Helm creates a K8s Secret automatically
      <key>: <value> # Each key becomes a file in the mounted secret directory
    secretName: <string> # Alternative: reference a pre-existing K8s Secret by name
```

#### How Secrets Work

There are two ways to provide secrets for satellite-managed MCP integrations:

| Method          | When to use                                                                                                                                        |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `secret:` block | Helm automatically creates a K8s Secret and mounts it. Simplest approach.                                                                          |
| `secretName:`   | References a K8s Secret that **already exists** in the cluster. Use when managing secrets externally (e.g., via Vault, External Secrets Operator). |

> **Do not use both** `secret:` and `secretName:` for the same integration. If neither is provided, no secrets are available at runtime.

**How it works under the hood**: The Helm chart creates a K8s Secret from the `secret:` block, mounts it as files at `/etc/secrets/<integration-name>/`, and the satellite reads those files at runtime. Each key in the `secret:` block becomes a file, and the file content becomes the secret value. At runtime, these secrets are merged into the connection object as top-level properties, making them available via JSONPath for `customAuthData.authSchema` (e.g., `$.token` resolves to the value of the `token` key from the secret).

#### Auth Method Examples

##### Token Authentication

The simplest approach for bearer token auth. The satellite automatically sends `Authorization: Bearer <token>`.

```yaml theme={null}
integrations:
  my-mcp-server:
    type: mcpIntegration
    create: true
    connection:
      mcpServerUrl: http://mcp-server.internal:8000/sse
      authMethod: token
      token: "my-secret-token-value"
```

##### OIDC (Client Credentials)

Use for MCP servers that authenticate via an external OIDC provider (e.g., Microsoft Entra). The satellite obtains and refreshes tokens automatically using the `client_credentials` grant.

```yaml theme={null}
integrations:
  my-mcp-server:
    type: mcpIntegration
    create: true
    connection:
      mcpServerUrl: http://mcp-server.internal:8000/sse
      authMethod: oidc
      oidcAuthData:
        clientId: "my-client-id"
        clientSecret: "my-client-secret"
        externalOidcProviderUrl: "https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token"
        externalOidcParameters: # Optional
          microsoftEntraApplicationId: "my-app-id" # For Microsoft Entra scope resolution
          scope: "custom-scope" # For non-Microsoft providers
          audience: "my-audience"
```

##### Custom Authentication

Use when you need full control over the header name and value (e.g., non-Bearer schemes, API keys, or custom headers).

```yaml theme={null}
integrations:
  my-mcp-server:
    type: mcpIntegration
    create: true
    connection:
      mcpServerUrl: http://mcp-server.internal:8000/sse
      authMethod: custom
      customAuthData:
        headerName: Authorization
        authSchema: "$.token" # JSONPath to resolve the header value
    secret:
      token: "Bearer my-secret-token-value"
```

`authSchema` is a JSONPath expression resolved against the connection object. At runtime, secrets are merged into the connection object, so `$.token` resolves to the value of the `token` key from the `secret:` block. You can also use `secretName:` to reference a pre-existing K8s Secret instead — see [How Secrets Work](#how-secrets-work).

##### OAuth

OAuth is configured through the Resolve AI UI when connecting a publicly accessible MCP server. The OAuth flow (authorization, token exchange, refresh) is managed automatically — no satellite configuration is needed.

##### No Authentication

```yaml theme={null}
integrations:
  my-mcp-server:
    type: mcpIntegration
    create: true
    connection:
      mcpServerUrl: http://mcp-server.internal:8000/sse
      authMethod: none
```

#### Deployment Notes

After changing the integration configuration in `values.yaml`:

1. Run `helm upgrade` to apply the changes
2. Ensure the satellite pod restarts (the K8s Secret and ConfigMap are only re-mounted on pod restart)
3. Once configured, the integration will appear on the [MCP Integrations page](https://app.resolve.ai/integrations/mcpIntegration/edit) and should be marked as healthy