Custom Integration

Overview

ZoomInfo MCP is an open MCP server. Any client that can complete an OAuth 2.0 Authorization Code flow and speak the MCP protocol can connect to it. This guide walks through what an engineering team needs to build a custom MCP client (or agent) that points at ZoomInfo.

Server Details

Create an MCP App in the DevPortal

Custom clients authenticate against an MCP App registered in the ZoomInfo Developer Portal. Each tenant manages its own apps; client credentials are issued per app, not per user.

If your app is intended for users outside your tenant, see the Partner App submission process↗. Internal-use apps work for any user inside your ZoomInfo organization without further review.

Authentication Flow

ZoomInfo MCP uses Authorization Code with PKCE. Each end user authenticates with their own ZoomInfo credentials, and tokens are bound to that user. Avoid shared service accounts: tools like Account Research personalize results based on the calling user's CRM context, and a shared identity loses that.

The flow your client implements:

1. Generate a PKCE code verifier and challenge.
2. Open the ZoomInfo authorization URL in the user's browser, passing your client_id, redirect URI, requested scopes, and the PKCE challenge.
3. The user signs in and approves the requested scopes.
4. ZoomInfo redirects to your callback URL with an authorization code.
5. Your client exchanges the code (plus the PKCE verifier and client_secret) at the token endpoint for an access token and refresh token.
6. Use the access token in the Authorization: Bearer <token> header on requests to https://mcp.zoominfo.com/mcp.
7. When the access token expires, use the refresh token to get a new one without prompting the user again.

Detailed endpoint references and example requests live in the API auth docs: Authorization Code Flow with PKCE↗ and Refresh Token Flow↗.

Connecting Your Client

Most MCP clients accept a server URL plus an OAuth configuration. The exact shape varies by client; the example below is the minimum config form, and your client library will wrap the OAuth handshake described above.

{
  "mcpServers": {
    "zoominfo": {
      "url": "https://mcp.zoominfo.com/mcp",
      "auth": {
        "type": "oauth2",
        "clientId": "<your-client-id>",
        "clientSecret": "<your-client-secret>",
        "redirectUri": "http://localhost:8080/callback"
      }
    }
  }
}

On first connection, the client calls tools/list to fetch the active set of tools and their schemas. This happens at the start of every session. Your client always sees the latest definitions without versioning overhead.

Tool Discovery

tools/list returns every tool the authenticated user has access to. Each definition includes:

• Name: the identifier passed to tools/call.
• Description: written for LLM routing. It states when to use the tool and what inputs it expects.
• Input schema: JSON Schema describing required and optional parameters.

// Example: tools/list response (abbreviated)
{
  "tools": [
    {
      "name": "lookup",
      "description": "Reference data for valid search filter values...",
      "inputSchema": {
        "type": "object",
        "properties": {
          "fieldName": {
            "type": "string",
            "description": "Field to lookup (e.g., management-levels, industries)"
          }
        },
        "required": ["fieldName"]
      }
    }
  ]
}

Calling a Tool

Use tools/call with the tool name and arguments:

{
  "method": "tools/call",
  "params": {
    "name": "search_companies",
    "arguments": {
      "industryId": "6374",
      "employeeCount": { "min": 100, "max": 1000 },
      "location": "United States"
    }
  }
}

Batch Sizes and Rate Limits

The rate limit is 25 requests per second per authenticated user. Build retry logic with exponential backoff for production workloads. Bulk extraction and scraping are prohibited under ZoomInfo's Acceptable Use Policy.

Error Handling

ZoomInfo returns standard HTTP status codes. Common ones:

Full error reference: ZoomInfo API documentation↗.

Context Management

Direct tools (Search, Enrich, Lookup) return data straight into the calling LLM's context window. Cap batch sizes to fit your model's window.

Research tools (Account Research, Contact Research) run a sub-agent layer that synthesizes large payloads before returning a focused summary. This keeps the calling context manageable even for deep account work.

API Reference

For the full ZoomInfo API and data schema reference, see docs.zoominfo.com/docs↗.