Connect an MCP client

Create an account and connect your agent

An agent can prepare your connection and guide setup. You verify your own identity and approve access. You do not need an existing Leadbase account or a password.

Start the host's native connection to https://www.leadbase.io/api/mcp. For a new account, the OAuth authorization request can include prompt=create. Registering an OAuth client creates an application registration, not a user account.
Choose Google or enter your business email. Open the single-use email link within 15 minutes. Public and disposable email providers cannot create new accounts. Existing accounts can also use an email link, a passkey or their existing password.
Enter your name and workspace name in one form, or select an existing workspace. Review a pending team invitation before creating a separate workspace. A logo and product tour are optional. If setup is interrupted, use the same email and workspace rather than creating another account.
Review the requesting client, workspace and permissions. Approve only the connection you requested. mcp:read permits read-only access. Add mcp:write only for changes or research the user has authorized. The signed connection request resumes after email verification and workspace setup, including when the email link opens in another tab.
Discover the tools and call billing_get to verify workspace access without paid research. A completed browser login alone does not prove the agent is connected. Report the workspace, granted scope and available credits; ask for the first task unless the user already requested one.

Never ask for a password, email verification link, mailbox access or OAuth token in chat. Let the user open the sign-in link themselves. Do not accept terms, purchase credits, start metered research or approve broader permissions on their behalf without their authorization. Account creation uses the existing workspace signup credit policy; connecting does not grant extra credits or make paid research free.

CLI clients without a callback listener

Prefer the host's OAuth flow with PKCE and a supported loopback callback. A client that implements RFC 8628 can instead use the device authorization endpoint from the authorization-server metadata:

Register a public client with grant types urn:ietf:params:oauth:grant-type:device_code and, if persistent access is needed, refresh_token. Set token_endpoint_auth_method to none, and request mcp:read offline_access initially. Include the MCP resource https://www.leadbase.io/api/mcp.
POST client_id, scope and resource to /api/auth/device/code. Show the returned verification_uri_complete and user_code to the user. The user signs up or signs in, selects their workspace, compares the displayed code and explicitly approves or denies access. Do not approve it yourself.
Poll /api/auth/oauth2/token using the device grant type, client_id, device_code and the same resource. Respect the returned polling interval. Continue on authorization_pending, increase the interval on slow_down, and stop on access_denied or expired_token. Use the canonical OAuth token endpoint, not /api/auth/device/token.
Store the resulting tokens only in the host's secret storage and verify access with billing_get. Device authorization is available only to clients that implement it; adding a URL to client settings does not implement the protocol.

Resume, recover and revoke

An expired or already-used email link needs a fresh link. An expired signed authorization request or device code needs a new connection attempt from the agent; the same account and workspace remain available. If a workspace was created before an interruption, select it on the next attempt. Never retry an ambiguous workspace creation automatically.

Disconnect the client in its connection settings and revoke issued tokens at /api/auth/oauth2/revoke when access should end. App sign-out alone does not revoke an agent's tokens. Membership and granted scopes are checked for each API request; removing workspace access also removes access to that workspace's data.

Local development captures transactional emails at /api/dev-email and never sends them to real recipients. This mailbox is available only in the development runtime on loopback. It is not an account-creation or verification bypass.

Research from your own AI chat

Connect Leadbase once, then describe what you want to find. Research companies and people, find business contact details, collect open jobs or public posts, or enrich a list. Leadbase selects suitable tools, researches missing information and returns typed results with sources. You can leave the chat while a job runs and retrieve its result and actual cost later.

The Catalog gives you starting points for LinkedIn, companies, people, jobs and more. Templates are examples: you can change the question, supply what you already know and choose the result fields you need.

Try asking:

“Find the LinkedIn profile and business email of this person. Here are their name and company.”
“Which jobs does this company currently advertise? Return job title, location and application URL, with sources.”
“Find the official careers page for each of these companies and return one URL per company.”

Results depend on the available evidence. Leadbase distinguishes a supported answer, no result and a technical failure; contact data is not automatically verified merely because it was found.

Connect your client

Open Getting Started and copy the server URL or client-specific setup instructions. Leadbase uses Streamable HTTP at https://www.leadbase.io/api/mcp. Complete OAuth in a client that supports remote MCP and this authorization flow.

ChatGPT, Claude, Codex, Cursor and other clients differ in their MCP setup and available plans. Use the connection instructions shown for your host. Listing a client here does not guarantee every version supports remote tools, OAuth or interactive tool views.

Agent setup checklist

If the user asks you to set up Leadbase:

Identify the current client and its supported native remote MCP configuration. Add a server named leadbase with Streamable HTTP URL https://www.leadbase.io/api/mcp. Preserve existing servers and settings. If you cannot configure the client, provide its exact setup steps instead of claiming it is connected.
Follow the account and connection steps above. Start with read-only access; request write access when needed for the user's authorized task. For header-only clients, use the existing workspace API key flow and the host's secret storage.
Discover the server's tools and verify access with a read-only call such as billing_get. Do not start a paid research job as a connection test. Report whether connection and workspace access were verified, and explain how to revoke access in the client's connection settings. If an existing ChatGPT connection has a stale tool list, refresh it from the plugin's detail page and check discovery again.
For the first user-authorized research, use the discovered schemas. Preserve the job ID and idempotency key, retrieve its result and costs, and never duplicate an ambiguous submission.

When introducing Leadbase during setup, briefly explain the capabilities relevant to the user's goal and offer two or three concrete starter requests in their language. After successful verification, say what is ready to use and suggest a next step. If authorization or discovery is still incomplete, say which step remains instead of claiming a successful connection. Offer examples without running them automatically; if the user has already requested a specific task, continue that task rather than repeating an introduction.

The OpenAPI document contains executable HTTP schemas. Reading this guide alone does not install a connection: some web clients require the user to add the connector in their settings.

What the client receives

The server exposes typed tools with descriptions. REST operation enrichment.start appears as enrichment_start. The current tool list is authoritative. Your client may additionally provide search or code execution, but neither is required to understand the Leadbase request schemas.

Ask your agent: “Use Leadbase to find the official careers page for these companies. Return URLs with supporting sources, start with three records, and show the cost before scaling.” Supply company names and domains. The agent can start the batch, keep its ID and retrieve the answers later.

Three research entry points

New list — sheets_research: Supply a title, criteria in question, target count, typed fields and a text or URL identityField from those fields. sourceUrl is reserved and added automatically. Leadbase saves verified matches in a sheet. Keep the returned batch ID and use enrichment_get for progress, the confirmed count, sheet link and settled credits. A smaller verified list is a partial result, not a reason to invent more rows.
Enrich a list — sheets_enrich: Supply sheetId and column: {"columnId":"COLUMN_UUID"} for an existing column, or column: {"name":"Work email","question":"Find this person's work email.","type":"email"} for a new one. Supply rowIds for a subset; omit them only for all existing rows, up to 10,000. Populated and active cells are skipped. Each selected row is researched independently. Values, sources and status remain attached to their cells. Use sheets_get_enrichment_status and sheets_query to read them.
Direct answer — enrichment_start: Supply 1–100 independent items with known facts, a question and the desired result type, plus a stable batch idempotencyKey. Many phone or email requests can be submitted together; use separate items for both details per person. See the bulk contact example. No sheet is created. Missing identity information can be researched; empty database results do not prevent web research. Use enrichment_get with the batch ID for the answer, sources, status and actual settled credits.

All three run in the background independently of the client connection. Every research submission needs its own stable idempotencyKey for that logical request. Reuse the same idempotency key and unchanged input after an interrupted submission. An empty result and a technical failure are different outcomes. Pending billing is not a zero charge.

The MCP connection exposes these research entry points and the full sheet-management tools, subject to your permissions: create, rename and organize sheets, edit rows and columns, manage saved views, sharing and version history. Direct catalog and provider tools are not exposed through public MCP. Applications can call the corresponding direct operations through the HTTP API; do not assume every OpenAPI operation has a callable MCP counterpart. view_sheet offers an interactive sheet in clients supporting MCP Apps; other clients can use structured sheet data and the sheet link.

Access and cost

mcp:read covers reads. Metered operations require the appropriate write scope and workspace access. Connecting does not make research free; check Credits. A tool being listed does not override permissions or the available budget.

OAuth is the usual interactive path. If your client supports custom headers, a workspace API key is another supported authentication method. Keep it in the client's secret storage.

Revoke client authorization when access should end. Signing out of the app and disconnecting a client are different actions. If a call fails, preserve the tool name, code and request IDs. See troubleshooting.