Skip to main content

Integrate an MCP server

This guide covers the transport and authentication options for connecting a Quick App to an MCP server: directly, with the mcp Toolset type, or through a Toolset registered in DIAL, with dial-mcp.

Choose a transport protocol​

MCP servers communicate over one of two transport protocols:

ProtocolValueWhen to use
Streamable HTTPstreamable_httpDefault. Standard HTTP request/response. Works for most MCP servers.
Server-Sent EventssseThe server streams tool results incrementally. Required for long-running tools.

In a Quick App manifest (mcp Toolset type):

{
  "mcp_server_info": {
    "url": "https://mcp.example.com/tools",
    "protocol": "streamable_http"
  }
}

In config.json (admin-provisioned toolset, dial-mcp type), the equivalent field is transport:

{
  "toolsets": {
    "my-server": {
      "endpoint": "http://mcp-server:5000/tools",
      "transport": "SSE"
    }
  }
}

Configure authentication​

No authentication​

The MCP server is publicly accessible or secured at the network level.

In a Quick App manifest:

{
  "mcp_server_info": {
    "url": "https://mcp.example.com/tools",
    "protocol": "streamable_http",
    "authorization": null
  }
}

In config.json:

{
  "toolsets": {
    "public-tools": {
      "endpoint": "http://mcp-server:5000/tools",
      "authType": "NONE"
    }
  }
}

Bearer token​

Use a static bearer token for server-to-server calls where the token does not expire or is managed externally.

In a Quick App manifest:

{
  "mcp_server_info": {
    "url": "https://mcp.example.com/tools",
    "protocol": "streamable_http",
    "authorization": {
      "type": "bearer",
      "token": "your-static-bearer-token"
    }
  }
}

The token is sent as an Authorization: Bearer <token> header on every request.

API key​

Use a static API key sent as a request header or query parameter.

In a Quick App manifest:

{
  "mcp_server_info": {
    "url": "https://mcp.example.com/tools",
    "protocol": "streamable_http",
    "authorization": {
      "type": "api_key",
      "key": "your-api-key",
      "name": "X-API-Key",
      "location": "header"
    }
  }
}

Set "location": "query" to send the key as a URL query parameter instead.

In config.json:

{
  "toolsets": {
    "keyed-server": {
      "endpoint": "http://mcp-server:5000/tools",
      "authType": "API_KEY"
    }
  }
}

When authType is API_KEY, users enter their own key in DIAL Chat. The key is stored encrypted (see Toolsets security settings for KMS configuration).

Basic authentication​

Use HTTP Basic authentication (username + password).

In a Quick App manifest:

{
  "mcp_server_info": {
    "url": "https://mcp.example.com/tools",
    "protocol": "streamable_http",
    "authorization": {
      "type": "basic",
      "username": "service-user",
      "password": "service-password"
    }
  }
}

The credentials are Base64-encoded and sent as an Authorization: Basic <encoded> header.

Client credentials (OAuth 2.0)​

Use the OAuth 2.0 client credentials flow for machine-to-machine authentication.

In a Quick App manifest:

{
  "mcp_server_info": {
    "url": "https://mcp.example.com/tools",
    "protocol": "streamable_http",
    "authorization": {
      "type": "client_id_secret",
      "client_id": "your-client-id",
      "client_secret": "your-client-secret",
      "token_url": "https://auth.example.com/oauth/token",
      "scope": "tools:read",
      "aud": "https://mcp.example.com"
    }
  }
}

DIAL fetches a token from token_url using the client credentials and caches it until expiry.

scope and aud are optional but often required by the authorization server.

OAuth 2.0 (user login flow)​

For MCP servers that require per-user authentication (the user logs into the MCP provider themselves), use authType: OAUTH in config.json:

{
  "toolsets": {
    "github": {
      "endpoint": "http://github-mcp:5000/tools",
      "authType": "OAUTH"
    }
  }
}

DIAL redirects users through the OAuth provider's authorization page. Users authenticate once; DIAL stores the token for subsequent calls. The toolset card in DIAL Chat shows MY CREDS when a user is logged in.

For OAuth to work, configure the redirect and resource settings in settings.json:

{
  "toolsets": {
    "security": {
      "allowedRedirectUris": ["https://your-dial-chat.example.com/callback"],
      "resourceHost": "your-dial-core.example.com",
      "scopesSupported": ["openid", "profile"]
    }
  }
}

See Toolsets & Miscellaneous for all OAuth security settings.

Authentication in DIAL Chat​

Users sign in to a Toolset that needs authentication from its details in the Catalog, or when they start a conversation with an agent that uses it. See Authentication in the DIAL Chat User Guide.

Restrict exposed tools​

Both the direct mcp config and the dial-mcp config support an allowed_tools array to limit which tools from the server are visible to the model:

{
  "type": "mcp",
  "name": "limited-server",
  "mcp_server_info": {
    "url": "https://mcp.example.com/tools",
    "protocol": "streamable_http"
  },
  "allowed_tools": ["web_search", "fetch_page"]
}

If allowed_tools is omitted or empty, all tools the MCP server exposes are available.

Troubleshooting​

SymptomLikely causeFix
App returns "Tool call failed" with no error detaildisplay_error_in_stage is false on the fallback configSet "display_error_in_stage": true temporarily to see the raw error
401 UnauthorizedToken expired or wrong credentialsRe-check the token/key; for OAuth toolsets, log out and back in
404 on tool endpointWrong url or protocol mismatchVerify the URL; try switching between streamable_http and sse
"Toolset not found" in Quick Appdeployment_id doesn't match a Toolset registered in DIALCheck the Toolset's ID
OAuth redirect failsallowedRedirectUris not configuredAdd the DIAL Chat callback URL to settings.json → toolsets.security.allowedRedirectUris

Further reading​