> For the complete documentation index, see [llms.txt](https://help.delpha.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.delpha.io/delpha-api-and-mcp/mcp.md). # MCP Connect your AI agents (Cursor, VS Code, Claude, ChatGPT) directly to Delpha's Data Quality APIs using the open Model Context Protocol (MCP). ### Model Context Protocol ( MCP ) Let your AI agents call the Delpha Data Quality APIs over the Model Context Protocol. The Delpha MCP server exposes the same Data Quality tools as the [Delpha API](/delpha-api-and-mcp/api.md) — Find, Validate, Enrich, Score — through the open MCP standard, so any MCP-compatible client (Claude, ChatGPT, Claude Code, Cursor, VS Code, Windsurf, Codex) can use them directly. Access is bound to your Delpha team: sign in with your Delpha account (recommended), or use an API key. {% hint style="info" %} **Server URL** — `https://mcp.delpha.ai/mcp` **Auth** — Sign in with your Delpha account (OAuth 2.1 with PKCE, recommended), or send a live API key as `Authorization: Bearer dlp_…` from clients that can't sign in. Manage connected clients, team access and API keys from [app.delpha.ai → Developer → MCP](https://app.delpha.ai/developer/mcp). **Releases** — what changed, and when, is on the [release notes.](/delpha-api-and-mcp/mcp/release-notes.md) {% endhint %} ### Connect to Delpha's MCP server Pick your client. Every guide signs you in with your Delpha account by default and shows the API-key alternative where the client supports one. {% tabs %} {% tab title="Claude" %} Claude on the web, Claude Desktop and Cowork connect through a **custom connector**, with your Delpha login — nothing to paste but the URL. Available on Free (one custom connector), Pro, Max, Team and Enterprise plans. 1. Open **Customize → Connectors**, click **+**, then **Add custom connector**. 2. Paste the server URL — `https://mcp.delpha.ai/mcp` — and click **Add**. Leave the advanced OAuth fields empty: Claude registers itself with the server. 3. Click **Connect** and sign in at app.delpha.ai. You are sent straight back to Claude. 4. In a chat, open **+ → Connectors** and switch Delpha on. On Team and Enterprise plans an owner adds the connector once under **Organization settings → Connectors**; members then find it under **Customize → Connectors** and click **Connect**. Details: Anthropic's [custom connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp). {% endtab %} {% tab title="ChatGPT & Codex" %} **ChatGPT** connects through developer mode, with your Delpha login. Available on Plus, Pro, Business, Enterprise and Education plans, on the web. 1. Open **Settings → Security and login** and turn on **Developer mode**. 2. Open ChatGPT's **Plugins** page, click **+**, and create a developer-mode app for the server: give it a name and set the MCP server URL to `https://mcp.delpha.ai/mcp`. Leave authentication on **OAuth** — ChatGPT discovers the rest. 3. When ChatGPT asks you to connect, sign in at app.delpha.ai. 4. In a chat, open the **+** menu, choose **Developer mode**, and pick Delpha. **Codex CLI** — add the server, then sign in: ```bash codex mcp add delpha --url https://mcp.delpha.ai/mcp codex mcp login delpha ``` To use an API key instead, point Codex at an environment variable that holds it, in `~/.codex/config.toml`: ```toml [mcp_servers.delpha] url = "https://mcp.delpha.ai/mcp" bearer_token_env_var = "DELPHA_API_KEY" ``` See OpenAI's [developer mode](https://developers.openai.com/api/docs/guides/developer-mode) and [Codex MCP](https://learn.chatgpt.com/docs/extend/mcp?surface=cli) documentation. {% endtab %} {% tab title="Claude Code" %} Add the server, then sign in from inside Claude Code: ```bash claude mcp add --transport http delpha https://mcp.delpha.ai/mcp ``` Run `/mcp` in Claude Code, pick **delpha** and finish the sign-in in your browser. Add `--scope user` to the command to make the server available in every project. To use an API key instead of signing in, pass it as a header: ```bash claude mcp add --transport http delpha https://mcp.delpha.ai/mcp \ --header "Authorization: Bearer dlp_live_..." ``` See the Claude Code [MCP documentation](https://code.claude.com/docs/en/mcp). {% endtab %} {% tab title="Cursor" %} [Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=delpha\&config=eyJ1cmwiOiJodHRwczovL21jcC5kZWxwaGEuYWkvbWNwIn0%3D) Click **Install in Cursor** to add the server, or add it to `~/.cursor/mcp.json` (or `.cursor/mcp.json` inside a project). Cursor prompts you to sign in at app.delpha.ai the first time it connects. ```json { "mcpServers": { "delpha": { "url": "https://mcp.delpha.ai/mcp" } } } ``` To use an API key instead, add a `headers` block: ```json { "mcpServers": { "delpha": { "url": "https://mcp.delpha.ai/mcp", "headers": { "Authorization": "Bearer dlp_live_..." } } } } ``` See Cursor's [MCP documentation](https://cursor.com/docs/mcp). {% endtab %} {% tab title="VS Code" %} [Install in VS Code](https://vscode.dev/redirect/mcp/install?name=delpha\&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.delpha.ai%2Fmcp%22%7D) Click **Install in VS Code** to add the server, or add it to `.vscode/mcp.json` in your workspace (or run **MCP: Add Server** from the Command Palette). VS Code opens the sign-in at app.delpha.ai the first time the server starts. ```json { "servers": { "delpha": { "type": "http", "url": "https://mcp.delpha.ai/mcp" } } } ``` To use an API key instead, add a `headers` block: ```json { "servers": { "delpha": { "type": "http", "url": "https://mcp.delpha.ai/mcp", "headers": { "Authorization": "Bearer dlp_live_..." } } } } ``` See the VS Code [MCP documentation](https://code.visualstudio.com/docs/agent-customization/mcp-servers). {% endtab %} {% tab title="Windsurf" %} Add the server to `~/.codeium/windsurf/mcp_config.json`, then refresh the servers from Windsurf's MCP settings. Windsurf prompts you to sign in at app.delpha.ai the first time it connects. ```json { "mcpServers": { "delpha": { "serverUrl": "https://mcp.delpha.ai/mcp" } } } ``` To use an API key instead, add a `headers` block: ```json { "mcpServers": { "delpha": { "serverUrl": "https://mcp.delpha.ai/mcp", "headers": { "Authorization": "Bearer dlp_live_..." } } } } ``` See Windsurf's [MCP documentation](https://docs.devin.ai/desktop/cascade/mcp). {% endtab %} {% tab title="Other MCP clients" %} MCP is an open protocol with a growing client ecosystem. Any client that speaks streamable HTTP can connect with the server URL alone — the server advertises its sign-in through the standard discovery documents (`/.well-known/oauth-protected-resource`, `/.well-known/oauth-authorization-server`, `/.well-known/openid-configuration`) and registers clients dynamically, so a compliant client negotiates auth by itself: ```json { "delpha": { "url": "https://mcp.delpha.ai/mcp" } } ``` If the client can't sign in, send a live API key as a bearer token in the `Authorization` header (most clients accept a `headers` property, as in the Cursor example). For a client that only runs local **stdio** servers, bridge it with [mcp-remote](https://www.npmjs.com/package/mcp-remote), which runs the sign-in for you: ```json { "mcpServers": { "delpha": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.delpha.ai/mcp"] } } } ``` {% endtab %} {% endtabs %} #### Authentication Two ways in, both bound to your Delpha team: * **Sign in with Delpha — OAuth 2.1 with PKCE (recommended).** Your client opens app.delpha.ai, you sign in, and every call is tied to your user account, so usage stays auditable per person. Use it wherever your client supports it — Claude, ChatGPT, Claude Code, Cursor, VS Code, Windsurf and Codex all do. * **API key.** A live `dlp_` key sent as `Authorization: Bearer dlp_…`, for headless agents, CI, and clients that can't complete a sign-in. Calls are attributed to the key and its team, and the key can be restricted to specific tools, a credit budget and an expiry. Test-mode keys are not served over MCP — see below. #### **Sign in with Delpha** 1. Have a Delpha account — [sign up](https://app.delpha.ai/signup) (your team is created with it) or accept a teammate's invitation. 2. Add the connector in your client with the server URL above. The server publishes standard OAuth discovery documents and registers clients dynamically, so there is no client ID or secret to enter. 3. Your client opens Delpha's sign-in page at app.delpha.ai. Sign in, and you are sent straight back to the client — there is no separate consent step. 4. The first connection sets up your team's MCP workspace automatically; the client keeps the session alive and asks you to sign in again when it expires. {% hint style="info" %} No account yet? Create one at [app.delpha.ai](https://app.delpha.ai/signup), or ask a team admin to invite you. Questions — . {% endhint %} #### **API key** Create a key from [**Developer → API keys**](https://app.delpha.ai/developer/api-keys). At creation you choose: * **Scopes** — the tools the key may call, as `dataquality..single` (the *API-key scope* column in the tools table below). A key with no scopes has full access. * **Credit limit** — an optional cap on what the key may spend per day, week or month, or in total. * **Expiry** — 365 days by default, anything from 1 to 730. * **Mode** — Live or Test mode. **MCP serves live keys only**: a test-mode key authenticates, then every tool call fails with `403 sandbox_key_unsupported`. Use a live key here and keep the test-mode key for the REST API. Then send it as a bearer token instead of signing in — for a JSON-configured client: ```json { "mcpServers": { "delpha": { "url": "https://mcp.delpha.ai/mcp", "headers": { "Authorization": "Bearer dlp_live_..." } } } } ``` A key can be revealed, renamed, re-scoped, rotated or revoked from the same page. A call outside a key's scopes fails with `403 insufficient_scope`, naming the scope it needs. {% hint style="warning" %} Treat a key like a password: store it in a secrets manager and never commit it. Give each client its own key with only the scopes it needs, so a leak is contained and revoking it disconnects one client, not all of them. Revoke a leaked key immediately from [Developer → API keys](https://app.delpha.ai/developer/api-keys). {% endhint %} ### Manage your MCP connection Everything about MCP lives under [**app.delpha.ai → Developer → MCP**](https://app.delpha.ai/developer/mcp): * **Connect a client** — the same per-client guides as above, with your team's server URL filled in, and a one-click way to create an API key and drop it into the config. * **Verify the connection** — waits for your client's first handshake and confirms it reached the server. * **Connected clients** — every client that has connected, signed in or by key, with its name and last-seen time. **Disconnect** removes a signed-in client; disconnecting a key-based client also revokes its key. * **MCP access** (team admins) — a team-wide switch that turns MCP off for both sign-in and keys. Changes apply within about a minute. New teams start with it on. API keys — scopes, credit limits, expiry, reveal, rotate, revoke — are managed from [**Developer → API keys**](https://app.delpha.ai/developer/api-keys), where each key's last-used time is shown. #### **Usage & credits** Every tool call draws from your team's Delpha credit balance — the same metering as calling the [Delpha API](/delpha-api-and-mcp/api.md) directly, and new teams start with free credits. When the balance reaches zero, tool calls return a payment-required error until the team is topped up. Each call is listed in [Developer → Logs](https://app.delpha.ai/developer/logs); track your balance and history at [Settings → Billing](https://app.delpha.ai/settings/billing) and [Settings → Usage](https://app.delpha.ai/settings/usage). ### Tools The MCP server exposes 16 tools, grouped by workflow below. Every tool maps to a Delpha API endpoint — click *API reference* on any row to see the full request/response schema on the existing API page. *API-key scope* is the scope a restricted key needs to call the tool (a key with no scopes can call them all). #### **Find & Validate** | MCP tool | Objective | Description | Live lookup | API-key scope | API reference | | ------------------------------------ | -------------------- | ------------------------------------------- | ----------- | ------------------------------------------ | --------------------------------------------------------------------------------------------- | | `findAndValidateUltimateParent` | Recommend / Validate | Find & validate ultimate parent | Yes | `dataquality.ultimate.single` | [ultimate-parent](https://help.delpha.io/delpha-api-and-mcp/api/ultimate-parent) | | `findAndValidateWebsite` | Recommend / Validate | Find & validate website | Yes | `dataquality.website.single` | [website](https://help.delpha.io/delpha-api-and-mcp/api/website) | | `findAndValidateLegalID` | Recommend / Validate | Find & validate legal ID | Yes | `dataquality.legal-id.single` | [legal-id](https://help.delpha.io/delpha-api-and-mcp/api/legal-id) | | `findAndValidateLinkedInCompanyPage` | Recommend / Validate | Find & validate a company's LinkedIn page | Yes | `dataquality.linkedin-company-page.single` | [linkedin-company-page](https://help.delpha.io/delpha-api-and-mcp/api/linked-in-company-page) | | `findAndValidateEmail` | Recommend / Validate | Find, validate & qualify email | Yes | `dataquality.email.single` | [email](https://help.delpha.io/delpha-api-and-mcp/api/email) | | `findAndValidatePhone` | Validate | Find & validate phone number | Yes | `dataquality.phone.single` | [phone](https://help.delpha.io/delpha-api-and-mcp/api/phone) | | `findAndValidateName` | Validate | Find & validate person name | Yes | `dataquality.name.single` | [name](https://help.delpha.io/delpha-api-and-mcp/api/name) | | `findAndValidateLinkedInProfile` | Recommend / Validate | Find & validate a person's LinkedIn profile | Yes | `dataquality.linkedin-profile.single` | [linkedin-profile](https://help.delpha.io/delpha-api-and-mcp/api/linked-in-profile) | #### **Result polling** | MCP tool | Objective | Description | Live lookup | API-key scope | API reference | | ------------------------------ | -------------------- | -------------------------------- | ----------- | ------------------------------------------ | --------------------------------------------------------------------------------------------- | | `getUltimateParentResult` | Recommend / Validate | Get ultimate-parent result | No | `dataquality.ultimate.single` | [ultimate-parent](https://help.delpha.io/delpha-api-and-mcp/api/ultimate-parent) | | `getWebsiteResult` | Recommend / Validate | Get website validation result | No | `dataquality.website.single` | [website](https://help.delpha.io/delpha-api-and-mcp/api/website) | | `getLegalIDResult` | Recommend / Validate | Get legal ID validation result | No | `dataquality.legal-id.single` | [legal-id](https://help.delpha.io/delpha-api-and-mcp/api/legal-id) | | `getLinkedInCompanyPageResult` | Recommend / Validate | Get LinkedIn company page result | No | `dataquality.linkedin-company-page.single` | [linkedin-company-page](https://help.delpha.io/delpha-api-and-mcp/api/linked-in-company-page) | | `getEmailResult` | Recommend / Validate | Get email validation result | No | `dataquality.email.single` | [email](https://help.delpha.io/delpha-api-and-mcp/api/email) | | `getPhoneResult` | Validate | Get phone validation result | No | `dataquality.phone.single` | [phone](https://help.delpha.io/delpha-api-and-mcp/api/phone) | | `getNameResult` | Validate | Get name validation result | No | `dataquality.name.single` | [name](https://help.delpha.io/delpha-api-and-mcp/api/name) | | `getLinkedInProfileResult` | Recommend / Validate | Get LinkedIn profile result | No | `dataquality.linkedin-profile.single` | [linkedin-profile](https://help.delpha.io/delpha-api-and-mcp/api/linked-in-profile) | *Live lookup* flags the tools annotated `openWorldHint=true` in the published API document: they resolve their answer when the call is made rather than reading it from a fixed list. Which systems a tool reaches, and what reaches them, is in **Data sources & privacy** below. A `get*Result` tool reads a job that already ran: reading one again never re-runs it and never charges again. A `findAndValidate*` call starts a job and spends credits, and re-submitting the same input starts another one. #### Tool behavior Most Delpha tools follow an asynchronous **submit → poll** pattern: 1. The agent calls a `findAndValidate*` tool with the input data. The server returns a `job_id` immediately. 2. The agent calls the paired `get*Result` tool with that `job_id` to fetch the result. While the job is still running, the result tool returns `status_code=202` and the agent retries; on completion it returns `status_code=200` with the full result envelope. Example pair: `findAndValidateEmail` → `getEmailResult`. Typical end-to-end latency is a few seconds. Every result envelope shares the same shape: `{ message, status, status_code, result, process_time }`. The `result` object is entity-specific — see the linked API page for each tool for the exact fields and scoring semantics. ### Data sources & privacy These tools return data about people, so what follows is where each one's result comes from, what personal data leaves Delpha, the role Delpha plays, and how anyone whose data was checked can reach Delpha. Delpha's providers are named individually, with the role each one plays, in [Delpha's sub-processor list](https://delpha.io/delpha-sub-processor-list/). * **`findAndValidateEmail`** — This result comes from Delpha's own verification and a Delpha model; no contact database and no third-party database is used. Candidate addresses are generated from per-domain address patterns, not retrieved from a list of known addresses. The address you supply — or an address formed from the name and company website you supply — reaches the mail infrastructure of that address's own domain. * **`findAndValidatePhone`** — This result is obtained by parsing the submitted number and verifying it against data from carriers and cross-carrier network enablers, through Delpha's providers. Delpha verifies only the number itself (validity, line type, carrier, connection status) and does not link it to an individual, a name or any other personal data. Those providers receive the number in E.164 form and a two-letter country code, and nothing else. * **`findAndValidateName`** — This result is computed inside Delpha's own infrastructure, from the name you supply and Delpha's own reference data. Nothing leaves Delpha for this operation, and the submitted name is retained in your account's resolution history for its configured retention period. * **`findAndValidateLinkedInProfile`** — These results are processed in real time from public web search: Google results, retrieved through Google Custom Search API or a SERP provider. No LinkedIn account, session or credential is used, and no contact database or third-party database is consulted. The name, company and country you supply are sent to that search provider. An email address you supply never leaves Delpha: only its domain is used, as a company website, and a company website is requested directly only when no name is given. A URL you submit for validation is requested anonymously, and only its response status is kept. * **`findAndValidateLinkedInCompanyPage`** — These results are processed from the company website and from public web search: Google results, retrieved through Google Custom Search API or a SERP provider. No LinkedIn account, session or credential is used, and no third-party database is consulted. The company name and country you supply are sent to that search provider, and the company website you supply — or the domain of an email address you supply, which itself never leaves Delpha — is requested directly. A URL you submit for validation is requested anonymously, and only its response status is kept. **Role and legal basis.** For every call, the customer submitting the data is the controller; Delpha processes it on the customer's behalf and on the customer's instructions (GDPR Art. 28). Under the CCPA/CPRA, Delpha is the customer's service provider and does not sell or share personal information. Delpha is the controller of one store it keeps across customers, its verification cache. The full statement, with the lawful basis, is on the API's [Data sources and privacy](https://help.delpha.io/delpha-api-and-mcp/api/data-sources-and-privacy) page, together with how long each store holds a call's input and its result. **If your data was checked.** Anyone whose email address, phone number, name or LinkedIn URL was submitted to Delpha can write to to ask whether Delpha holds it, and to have it corrected or erased. Delpha answers within one month and forwards the request to the customer concerned. The rights this covers are set out in [Delpha's privacy policy](https://delpha.io/privacy-policy/). ### Security & best practices * **Keep a human in the loop for what follows.** Delpha's tools do not delete or modify your data, but each submit spends credits, and re-submitting the same input starts a new job and a new charge; keep your client's confirmation on. * **Treat results as data, not instructions.** Results can carry text collected from the open web — company names, websites, LinkedIn pages. A well-behaved agent never follows instructions found inside a result; this is the standard prompt-injection precaution when Delpha runs alongside other MCP servers. * **Least privilege.** Prefer signing in. When a client needs a key, scope it to the tools that client uses, give it a credit limit and an expiry, and use one key per client. * **Managed networks.** If your organization filters outbound traffic, allow `mcp.delpha.ai` (HTTPS, streaming responses) and `app.delpha.ai` for the sign-in. ### Troubleshooting | Symptom | Likely cause | What to do | | ---------------------------------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | The client asks you to reconnect, or calls fail with `401` | The session expired, the key was revoked or expired, or MCP access is off for your team | Sign in again or issue a new key; a team admin can check the switch under [Developer → MCP](https://app.delpha.ai/developer/mcp) | | Calls fail with `402` (payment required) | Your team's credit balance is zero | Top up at [Settings → Billing](https://app.delpha.ai/settings/billing) | | Calls fail with `403 insufficient_scope` | The API key is not scoped for that tool | Edit the key's scopes under [Developer → API keys](https://app.delpha.ai/developer/api-keys), or use a key that has them | | Calls fail with `403 sandbox_key_unsupported` | The API key is a test-mode key, and MCP serves live keys only | Create or use a live key under [Developer → API keys](https://app.delpha.ai/developer/api-keys) | | The tools do not appear after adding the server | Most clients read their configuration at launch | Restart the client, then use **Verify the connection** under [Developer → MCP](https://app.delpha.ai/developer/mcp) | | The sign-in page never opens, or the connection is refused | A corporate proxy or firewall blocks the host | Allow `mcp.delpha.ai` and `app.delpha.ai` | **Feedback** We're actively adding tools and refining descriptions based on how agents actually use them. If you have feedback, hit a rough edge, or want to see a new capability, email us at . *** ### Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://help.delpha.io/delpha-api-and-mcp/mcp.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. We're actively adding tools and refining descriptions based on how agents actually use them. If you have feedback, hit a rough edge, or want to see a new capability, email us at .MCP --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://help.delpha.io/delpha-api-and-mcp/mcp.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.