Skip to main content

​
What is MCP?

The Model Context Protocol (MCP) 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 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 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: 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:
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: Gradial combines the base URL and endpoint path when connecting — https://cdp-api.example.com plus /mcp results in:
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:
Too broad:
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

Open the MCP integration dialog

  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.
2

Enter the server details

  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.
3

Configure authentication

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:
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)
  • OAuth Authorization Server Metadata (RFC 8414) or OpenID Connect discovery
  • PKCE with the S256 challenge method
  • OAuth Dynamic Client Registration (RFC 7591)
  • 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:
See Gradial’s 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 PassthroughBefore using SSO Passthrough, configure the identity provider under Organization → SSO. See Setting Up 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.
4

Add required headers

Use Additional Headers only for static, non-authentication values required by the MCP server, such as:
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.
5

Validate and create the integration

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.
6

Assign the integration to Environments

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.
7

Connect each user for Browser OAuth

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:
Example:

​
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:
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:

​
Troubleshooting

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 for help with network allowlisting, organization-specific authentication options, or MCP connection troubleshooting.