> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gradial.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Custom MCP Agent Integration
> Extend Gradial using Model Context Protocol (MCP) — connect proprietary data sources, internal knowledge bases, and custom tools beyond the native catalog.
***
## What is MCP?
The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard for connecting AI agents to external data and tools. Developed by Anthropic and adopted across the industry, MCP is becoming the common language enterprises use to expose data to AI systems—regardless of which vendor's agents are consuming it.
Think of MCP as a universal adapter. Instead of building custom integrations for every AI platform, you build one MCP server and any compliant agent can use it. This matters for enterprises because:
* **Standardization** — Define once how your data is accessed, enforce it everywhere. Your CDP, product catalog, and internal knowledge base speak the same protocol whether Gradial, your internal tools, or other vendor agents are calling them.
* **Interoperability** — As more platforms adopt MCP, your agents can communicate with each other. A Gradial agent executing a content workflow can hand off to another vendor's agent for specialized tasks, passing context seamlessly.
* **Future-proofing** — Investing in MCP means your data infrastructure works with tomorrow's AI tools, not just today's. The protocol is designed to evolve with the ecosystem.
* **Control** — You decide exactly what data and capabilities to expose. MCP servers sit in your infrastructure, behind your security controls, serving only what you explicitly permit.
Gradial's MCP integration lets you connect any MCP-compliant server—whether you've built it yourself, deployed an open-source implementation, or are using a vendor's MCP endpoint—and immediately extend what Gradial agents can do.
***
## Why Connect an MCP Agent?
MCP integrations let you extend what Gradial agents can do without waiting for native integrations. Common use cases include:
* **First-party data access** — Connect your CDP, data warehouse, or customer database so agents can personalize content using real audience data
* **Internal tool access** — Expose internal APIs, proprietary calculators, or business logic to agents
* **Custom content sources** — Pull from internal knowledge bases, product catalogs, or pricing systems
* **Workflow automation** — Trigger actions in systems that don't have native Gradial integrations
***
## How the Connection Fits Together
Before starting setup, it helps to understand how the pieces connect:
1. Your organization hosts or selects an MCP server with the tools you want Grady to use.
2. An MCP integration is created once for your Gradial organization, then enabled for one or more Gradial Environments. Workspaces inherit access through their associated Environments.
3. A Gradial administrator creates the integration under **Settings → Integrations** and supplies the server URL, authentication settings, and a description of its capabilities.
4. Gradial validates the MCP session and tool list for shared-credential and SSO connections. For browser OAuth, Gradial validates OAuth discovery and client registration when the integration is created.
5. The administrator assigns the MCP integration to one or more Gradial Environments.
6. Grady uses the capabilities description and discovered tools to determine when the MCP integration is relevant.
7. If the server uses browser-based MCP OAuth, each Gradial user authorizes their own account before using the integration.
***
## Prerequisites
Before you begin, make sure you have:
* A running MCP server that supports remote HTTP connections
* The server's base URL and MCP endpoint path
* Authentication credentials or OAuth configuration for the server
* For Browser OAuth (MCP spec), the ability to allowlist Gradial's [callback URI](#gradials-oauth-callback-uri) on your authorization server if it does not accept dynamically registered redirect URIs
* An organization role with permission to manage Gradial settings and integrations
* The Gradial Environment or Environments that should have access to the integration
Your MCP server must:
* Be reachable from Gradial's infrastructure
* Accept MCP JSON-RPC requests over HTTP
* Support `initialize`, `notifications/initialized`, `tools/list`, and `tools/call`
* Advertise the MCP `tools` capability during initialization
* Return MCP responses as JSON or a server-sent event stream
If your MCP endpoint restricts inbound traffic by source IP, allowlist Gradial's outbound egress IP addresses on your firewall or reverse proxy. See [IP Allowlisting](/docs/integrations-administration-and-setup/ip-allowlist) for the current list.
Use HTTPS for production MCP endpoints. Give Gradial only the network access and server permissions required for the tools you intend to expose.
***
## Authentication Methods
Gradial supports the following authentication methods for external MCP servers:
| Method | Best for | Identity model | Required configuration |
| ----------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **API Key** | Servers protected by a shared static token | One credential shared by all users of the integration | API key, header name, and optional value prefix |
| **Browser OAuth (MCP spec)** | Per-user authorization | Each Gradial user connects their own account | MCP OAuth metadata, PKCE, Dynamic Client Registration, and Gradial's [callback URI](#gradials-oauth-callback-uri) on the server |
| **OAuth2 Client Credentials** | Most service-to-service integrations | One OAuth client shared by all users of the integration | Client ID, client secret, token URL, and optional scopes |
| **SSO Passthrough** | Internal MCP servers protected by the same identity provider as Gradial | Uses each user's existing SSO session | A configured Gradial [SSO provider](/docs/integrations-administration-and-setup/managing-access/sso) and the token type expected by the MCP server |
The authentication methods available in the setup dialog depend on your organization's Gradial configuration.
Use **OAuth2 Client Credentials** for most MCP integrations. It gives Gradial a dedicated service identity, avoids per-user authorization setup, and is easier to operate for shared Environment workflows. Use **Browser OAuth (MCP spec)** only when the MCP server must act on behalf of each individual Gradial user. This is called on-behalf-of (OBO) access: the external system checks the user's own permissions instead of using one shared service identity.
Use **SSO Passthrough** when users already authenticate to Gradial and the MCP server through the same identity provider, and the MCP server accepts that provider's access or ID token.
Use **API Key** when the MCP server expects a static token in a request header.
Shared API keys and client credentials give every user with access to the integration the same server permissions. Use a least-privileged service account and avoid personal credentials.
### Gradial's OAuth Callback URI
Browser OAuth (MCP spec) sends each user back to Gradial after they authorize the connection. Gradial's redirect URI is:
```text theme={null}
https://app.gradial.com/api/integrations/mcp-oauth/callback
```
Gradial submits this URI when it dynamically registers itself as an OAuth client, so most servers that fully support Dynamic Client Registration need no additional setup.
Register or allowlist the URI manually when your authorization server:
* Validates redirect URIs against a fixed allowlist, even for dynamically registered clients
* Restricts redirect URIs by hostname or domain
* Requires security review or change approval before accepting a new redirect target
Enter the URI exactly as shown. OAuth redirect URI matching is exact — a trailing slash, an added path segment, or `http` instead of `https` causes the authorization request to be rejected.
The callback URI applies only to **Browser OAuth (MCP spec)**. API Key, OAuth2 Client Credentials, and SSO Passthrough do not use a browser redirect, so no callback URI is needed.
***
## Connection Details
The following values are needed when creating an MCP connection:
| Field | Description | Example |
| ---------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| **Integration Name** | A clear name users can reference when asking Grady to use the integration | `Customer Data Platform` |
| **MCP Base URL** | The scheme and host for the MCP server, without the endpoint path | `https://cdp-api.example.com` |
| **MCP Endpoint Path** | The relative path to the MCP HTTP endpoint | `/mcp` |
| **Grady Capabilities** | A specific description of the data and actions available through the server | `Query customer segments, retrieve audience attributes, and look up product affinity scores.` |
Gradial combines the base URL and endpoint path when connecting — `https://cdp-api.example.com` plus `/mcp` results in:
```text theme={null}
https://cdp-api.example.com/mcp
```
If you paste a full MCP endpoint into **MCP Base URL**, Gradial extracts its path into **MCP Endpoint Path**. Review both fields before validating the connection.
The endpoint path must be relative to the base URL. Do not enter a second absolute URL in the endpoint path field.
### Write a Useful Capabilities Description
The **Grady Capabilities** field helps Grady decide when to use the MCP integration. Describe the tasks, data, and actions the server supports instead of describing only the underlying system.
Good:
```text theme={null}
Query customer segments, retrieve audience attributes, look up product
affinity scores, and fetch personalization rules by segment ID.
```
Too broad:
```text theme={null}
Access our customer platform.
```
The capabilities description helps with tool selection, but it is not an access-control policy. Enforce authorization and data restrictions on the MCP server.
For optimal performance, expose no more than 20 tools through a single MCP integration. Smaller, task-focused tool sets help Grady choose the right tool and reduce the amount of tool schema context sent to the model. If your MCP server supports more than 20 tools, create separate MCP integrations by workflow, data domain, or Environment instead of exposing every tool through one connection.
***
## How to Connect
1. Sign in to Gradial with permission to manage organization settings.
2. Go to **Settings → Integrations**.
3. Click **Connect Integration**.
4. Under **Web & developer tools**, select **MCP Server**.
The **Add MCP Integration** dialog opens.
1. Enter a descriptive **Integration Name**.
2. Enter the **MCP Base URL**.
3. Confirm or update the **MCP Endpoint Path**. The default is `/mcp`.
4. Describe the server's tools in **Grady Capabilities**.
Follow the instructions for your server's authentication method.
**API Key**
1. Select **API Key**.
2. Enter the API key.
3. Set **Header Name** to the header expected by the server. The default is `Authorization`.
4. Set **Prefix** to the value expected before the key. The default is `Bearer`.
5. Add any required non-authentication headers under **Additional Headers**.
6. Click **Validate Connection**.
Example request header:
```http theme={null}
Authorization: Bearer your-api-key
```
For a server that expects `X-API-Key` without a prefix, set **Header Name** to `X-API-Key` and leave **Prefix** empty.
**Browser OAuth (MCP spec)**
1. Select **Browser OAuth (MCP spec)**.
2. Add any required non-authentication headers under **Additional Headers**.
3. Click **Create Integration**.
During creation, Gradial probes the MCP endpoint for its OAuth challenge, discovers the server's protected-resource metadata, discovers the authorization server, confirms support for PKCE using `S256`, and dynamically registers Gradial as an OAuth client.
The MCP server and its authorization server must support:
* OAuth Protected Resource Metadata ([RFC 9728](https://www.rfc-editor.org/rfc/rfc9728))
* OAuth Authorization Server Metadata ([RFC 8414](https://www.rfc-editor.org/rfc/rfc8414)) or OpenID Connect discovery
* PKCE with the `S256` challenge method
* OAuth Dynamic Client Registration ([RFC 7591](https://www.rfc-editor.org/rfc/rfc7591))
* The authorization code and refresh token grants
Gradial registers the following redirect URI during client registration. If your authorization server allowlists redirect URIs, add it before creating the integration:
```text theme={null}
https://app.gradial.com/api/integrations/mcp-oauth/callback
```
See [Gradial's OAuth Callback URI](#gradials-oauth-callback-uri) for details.
Browser OAuth does not use **Validate Connection** before the integration is created. Gradial verifies OAuth discovery and client registration during creation. Each user completes authorization after the integration has been saved.
**OAuth2 Client Credentials**
1. Select **OAuth2 Client Credentials**.
2. Enter the **Client ID** and **Client Secret**.
3. Enter the authorization server's **Token URL**.
4. If required, enter the server's scopes in **Scope**, separated by spaces.
5. Add any required non-authentication headers under **Additional Headers**.
6. Click **Validate Connection**.
Gradial obtains and refreshes access tokens automatically using the shared OAuth client. The token endpoint must accept the client credentials through HTTP Basic authentication.
**SSO Passthrough**
Before using SSO Passthrough, configure the identity provider under **Organization → SSO**. See [Setting Up SSO](/docs/integrations-administration-and-setup/managing-access/sso).
1. Select **SSO Passthrough**.
2. Select the **SSO Provider** associated with the MCP server.
3. Select the **Token Source**:
* **Access token** — Recommended for most MCP servers
* **ID token** — Use only when the MCP server specifically requires identity claims
4. If required, enter one **Required Scope**, such as `mcp.read`. The required scope must be a single scope token without spaces. If configured, Gradial checks for it before calling the MCP server.
5. Add any required non-authentication headers under **Additional Headers**.
6. Click **Validate Connection**.
Gradial validates the connection using the current user's SSO session. Users with an active session from the selected SSO provider can use the MCP integration without a separate consent flow. Users without that SSO session must sign in through SSO before using it.
Use **Additional Headers** only for static, non-authentication values required by the MCP server, such as:
```http theme={null}
X-Client-Id: customer-tenant-123
```
Do not add authorization, API key, content negotiation, or MCP session headers here. Gradial manages those through the selected authentication method and MCP protocol.
Every additional header requires a unique name and a non-empty value.
For API Key, OAuth2 Client Credentials, and SSO Passthrough:
1. Click **Validate Connection**.
2. Confirm that Gradial reports a successful connection and the number of tools found.
3. Click **Create Integration**.
For Browser OAuth, click **Create Integration** after completing the server details. OAuth discovery and client registration occur during creation.
Connection validation initializes the MCP session and requests `tools/list`. It does not execute one of the server's business tools.
The integration exists at the organization level after it is created, but Grady can use it only in Environments to which it is assigned.
1. Return to the integrations list.
2. Find the new MCP integration.
3. Open its Environment selector. A new integration may show **No environment**.
4. Select each Environment that should have access to the MCP server.
All Workspaces associated with those Environments can use the integration.
Complete this step only when the integration uses **Browser OAuth (MCP spec)**.
Each user who needs the MCP integration must:
1. Go to **Settings → Integrations**.
2. Find the MCP integration.
3. Click **Connect**.
4. Sign in to the MCP server's authorization provider.
5. Review and approve the requested access.
6. Return to Gradial and confirm the integration shows **Connected**.
The same Gradial user who starts the OAuth flow must complete it. Authorization is stored per user and is not shared with other members of the Environment.
***
## What Gradial Validates
When you click **Validate Connection**, Gradial:
1. Builds the full MCP URL from the base URL and endpoint path.
2. Applies the selected authentication method and additional headers.
3. Sends an MCP `initialize` request.
4. Confirms that the server advertises the `tools` capability.
5. Sends `notifications/initialized`.
6. Sends `tools/list`.
7. Reports the number of tools returned by the server.
A successful validation confirms connectivity, authentication, MCP initialization, and tool discovery. It does not guarantee that every discovered tool will succeed for every input or user.
***
## Using Your MCP Agent
Once connected and assigned to an Environment, your MCP agent becomes available to Gradial agents automatically. The agent capabilities description helps Gradial decide when to use your MCP tools.
To explicitly invoke your MCP agent in a prompt or workflow:
```text theme={null}
Use the {Integration Name} agent to [describe the task].
```
Example:
```text theme={null}
Use the HubSpot MCP Agent to pull the top 5 customer segments
by engagement score for the Q4 campaign.
```
### Test the Integration in Grady
After assigning the integration to an Environment, open a Workspace associated with that Environment and ask Grady to perform a low-risk read operation. Reference the integration by name to make the first test explicit:
```text theme={null}
Use the Customer Data Platform agent to list the available customer
segments. Return only each segment's name and identifier.
```
Confirm that:
* Grady selects the expected MCP integration
* The server receives the request under the expected user or service identity
* The response contains only data the identity is authorized to access
* No unexpected write operation occurs
After the initial test, Grady can select the MCP integration automatically when its capabilities description matches a task.
***
## Example: First-Party Data MCP
A common pattern is connecting a first-party data MCP to personalize content at scale.
**Setup:**
* **Integration Name:** `Customer Data Platform`
* **MCP Base URL:** `https://cdp-api.yourcompany.com`
* **MCP Endpoint Path:** `/mcp`
* **Authentication:** `OAuth2 Client Credentials`
* **Grady Capabilities:** "Query customer segments, retrieve audience attributes, look up product affinity scores, and fetch personalization rules by segment ID."
* **Environment:** `Production Marketing`
**Use case:** When creating landing page variants, Gradial agents can query your CDP to understand which segments exist, what attributes define them, and which messaging resonates with each—then generate on-brand content tailored to each audience.
**Test prompt:**
```text theme={null}
Use the Customer Data Platform agent to return the top five customer
segments by engagement score for the Q4 campaign.
```
***
## Troubleshooting
| Issue | Likely cause | Resolution |
| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Validate Connection** is unavailable | A required field is empty, the URL is invalid, or an additional header is incomplete | Review the base URL, authentication fields, capabilities description, and every additional header row |
| Connection times out or reports an unknown host | Gradial cannot reach the MCP server | Verify DNS and HTTPS configuration, then update firewall rules or allowlists so Gradial can reach the endpoint |
| MCP initialization fails | The endpoint is not an MCP HTTP endpoint or does not support the initialization handshake | Confirm the base URL and endpoint path, then test `initialize` directly against the server |
| Server does not advertise tool capabilities | The `initialize` response does not include the MCP `tools` capability | Update the MCP server to advertise tool support |
| `tools/list` fails | Authentication is valid for the endpoint but cannot list tools, or the server returns an invalid MCP response | Review server permissions, logs, response content type, and JSON-RPC response |
| Browser OAuth discovery fails | Protected-resource metadata, authorization-server metadata, PKCE, or Dynamic Client Registration is missing or invalid | Validate the server's OAuth metadata and confirm that PKCE `S256` and client registration are supported |
| Authorization server reports an invalid or unregistered `redirect_uri` | The authorization server does not accept Gradial's dynamically registered redirect URI | Add `https://app.gradial.com/api/integrations/mcp-oauth/callback` to the authorization server's allowed redirect URIs, matching it exactly |
| Browser OAuth user sees **Not connected** | The current user has not completed authorization | Click **Connect** on the integration and complete the OAuth flow as the same Gradial user |
| SSO validation reports a missing scope | The user's current identity-provider grant does not contain the configured scope | Add the scope at the identity provider, then sign out and back in to refresh the user's grant |
| Integration is not available in a Workspace | The integration is not assigned to the Workspace's Environment | Return to **Settings → Integrations** and add the correct Environment to the integration |
| Existing credentials need to be changed | Connection secrets cannot be viewed or replaced from the integration metadata editor | Create a new integration with the updated credentials, validate it, assign its Environments, and then retire the old integration |
When troubleshooting, compare the MCP server logs with the validation attempt. The server should receive `initialize`, `notifications/initialized`, and `tools/list` in that order.
***
## Security Recommendations
* Expose only the MCP tools Gradial needs. Keep each MCP integration to 20 tools or fewer for best performance.
* Apply authorization to every tool on the MCP server; do not rely on the capabilities description for enforcement.
* Use separate credentials and endpoints for development, staging, and production where possible.
* Use least-privileged scopes for OAuth clients and API keys.
* Treat tool descriptions and tool results as untrusted input and avoid returning secrets.
* Review write-capable tools carefully before assigning the integration to production Environments.
* Monitor authentication failures, tool calls, rate limits, and server errors.
***
## Need Help?
Contact your Gradial representative or [Gradial Support](https://portal.usepylon.com/) for help with network allowlisting, organization-specific authentication options, or MCP connection troubleshooting.