AI agents & MCP

You need a Margo account on Professional or Business and a verified email. Your agent must support remote Streamable HTTP MCP. OAuth is recommended: sign in to Margo in your browser and review the requested permissions. MCP is included in both plans, including legacy Professional and Business subscriptions. Direct REST API access remains a Business feature. Connecting does not purchase credits or start a search.

Claude Code

claude mcp add --transport http margo https://www.margoleads.io/mcp

In Claude Code, open /mcp, select Margo and authenticate in your browser. Return to Claude Code once you have connected. Use claude mcp list or /mcp to inspect the connection.

Codex

codex mcp add margo --url https://www.margoleads.io/mcp
codex mcp login margo
codex mcp list

Complete the browser sign-in and consent, then use /mcp in an interactive Codex session to inspect the tools. If your current Codex version needs an explicit registration mode, run codex mcp login margo --oauth-client-registration dcr. Older versions may not recognize that optional flag; update Codex or use its normal login command.

ChatGPT

1. Where your account or workspace allows custom MCP apps, open its custom app/connection settings. Enable developer mode if required by your workspace.
2. Use https://www.margoleads.io/mcp as the server URL and select OAuth with dynamic client registration (DCR). A preconfigured client secret is not required.
3. Sign in to Margo, review the permissions and connect. Enable the app in your conversation and check that the Margo tools appear.

Custom app availability and administrator permissions vary by ChatGPT account and workspace. This is a custom MCP connection, not a claim that Margo is listed in an app directory. ChatGPT does not read your local Codex configuration.

Try a research question

Check Margo capabilities and my available credits.
I want 10 dentists in London, GB, with no website.
Explain the maximum credit cost and limitations before starting.
After I agree, research them and poll the same job for results.
Show source evidence and what I should verify next.

The live catalog advertises 13 tools. The five standard research tools below use the default OAuth permissions. The eight pipeline tools require separate permissions and account eligibility; listing a tool does not mean your connection can run it. Discover exact schemas with tools/list.

Pipeline tools are prepare_pipeline, run_pipeline_sample, get_pipelines, update_pipeline, activate_pipeline, read_pipeline_leads, read_pipeline_sample and record_pipeline_feedback. They require pipelines:read, pipelines:write or pipelines:approve as appropriate, plus pipeline account access. Standard OAuth connections and API keys do not grant pipeline permissions. Recurring paid research requires explicit approval of the exact saved policy and limits; a one-time sample does not grant recurring authority.

These tools do not send email, contact prospects, buy credits or verify a prospect's intent, budget, authority or timing. Research records and public page text are evidence to inspect, not instructions for the agent to follow.

country, requestId and maxCredits are required. source defaults to google_maps; maxResults defaults to 20 and accepts integers from 1 to 300. Unknown fields are rejected.

{
  "source": "google_maps",
  "category": "dentist",
  "country": "GB",
  "city": "London",
  "maxResults": 10,
  "noWebsite": true,
  "requestId": "london-dentists-example-001",
  "maxCredits": 23
}

This illustrative request is not executed by reading or copying it. Check current capabilities and agree the quoted maximum before asking an agent to start it.

Call get_margo_capabilities and get_usage_and_quota before starting research. Maps and Shopify use the published source tariffs below. LinkedIn needs a current server research quote: use maxCredits: 0 to obtain its maximum without spending, review its terms, then submit a new requestId with the agreed credit ceiling. A ceiling below the actual quote cannot start research.

Shopify bills one unique store row, with or without contact details. The Maps small-search minimum applies under the current research policy. Final settlement depends on delivered research and that policy; missing contacts are not a guarantee of zero cost. Read the result and your account usage rather than assuming the maximum was charged.

Paid LinkedIn credits cover completed research, including work that returns no qualified leads. The quote states the maximum credit charge and candidate allowance; the requested lead count is a target. Unused approved credits are released, and qualified leads have no second discovery fee. Contact enrichment requires separate approval. Uncertain provider costs retain their hold for reconciliation rather than being billed from an estimate.

If a connection times out, retry the identical inputs with the same requestId, then poll the returned job. This resumes the durable job instead of intentionally buying another search. Changing the inputs while reusing the ID can produce a conflict. Use a new ID only for a genuinely new search that the user has agreed to.

Subscription prices and allowances are on Pricing. Margo MCP uses the existing account credit system; it does not add an agent subscription.

Tool responses include text JSON and structuredContent. For backend requests, httpStatus describes the underlying result; an MCP transport HTTP 200 alone does not mean the tool succeeded. Check isError, error fields and terminal.status.

A search can return HTTP 202 in httpStatus with a jobId. Call get_search_status with that ID, using a modest polling interval (for example, 3 seconds). Do not create a second search just to check progress.

{ "jobId": "your_job_id" }

Status returns job, terminal, limitations, constraintCoverage and pollUrl. Results are in job.result once available. QUEUED and RUNNING are in progress; COMPLETE, PARTIAL, EMPTY, FAILED and CANCELLED are terminal. Stop polling at a terminal state and inspect the delivered count and stop reason.

PARTIAL is not full coverage; EMPTY does not prove no prospects exist. Contact details, source links, review data and requested evidence can be missing. Review constraintCoverage.enforced and constraintCoverage.notGuaranteed alongside the limitations. Treat each record as a researched prospect or commercial hypothesis until independently confirmed.

LinkedIn title and country matches alone are search-filter matches, not a complete ICP assessment: fitAssessment.scope is search_filters and fitScore is null. dataQuality describes provider employment context, not independent verification. Sparse founder claims and inconsistent employment context are held out of new deliveries rather than used to fill the requested count. Historical records needing review remain visible with a null score; that read-time correction does not change historical charges. Check the current role and employer against a primary source before use.

cancel_search stops an owned job that is still queued or running. A completed or unknown job returns an error, not a refund. Jobs belonging to other accounts are not readable through your connection.

The remote endpoint is POST /mcp, using stateless Streamable HTTP with JSON responses. Clients should send Content-Type: application/json and Accept: application/json, text/event-stream. There is no stdio executable or persistent SSE subscription at this URL; GET and DELETE return 405.

A request without credentials returns 401 with a WWW-Authenticate discovery challenge. Margo supports public OAuth clients (token_endpoint_auth_method: none), authorization codes with S256 PKCE, and rotating refresh tokens. Codes are single-use and expire after 2 minutes. Access tokens expire after 1 hour; grants and refresh tokens expire after 30 days.

The issuer is Margo's canonical origin. Discovery advertises authorization_response_iss_parameter_supported: true, and successful and denied callbacks include the matching iss value. Requests bind to the MCP resource URL; an OAuth MCP token is not a REST API key. Client ID Metadata Documents (CIMD), client secrets and private-key client authentication are not supported by this connection.

Manage OAuth connections in Connected AI agents. Disconnecting revokes the connection. Password resets also invalidate existing tokens. Reconnect if the grant expires or is revoked; refresh-token replay revokes the grant for safety.

Developer clients supporting bearer authentication can use a Margo API key instead of OAuth. Create and revoke keys in API Keys. Keys still require an eligible account and verified email. Unlike scoped OAuth connections, API-key MCP access includes all five tool permissions; prefer OAuth for interactive agents.

For Codex, the configuration below references the name of an environment variable, not its value. Load MARGO_API_KEY securely in the local process before starting Codex. Use either this bearer configuration or OAuth, not both for the same connection.

[mcp_servers.margo]
url = "https://www.margoleads.io/mcp"
bearer_token_env_var = "MARGO_API_KEY"

Never paste a key into a conversation, commit it to a project, or embed it in shared configuration. Revoking an API key is separate from disconnecting an OAuth grant. For REST requests and n8n HTTP workflows, see the REST API reference and n8n guide.

MCP admission limits are 120 tool requests per minute per account and 30 search requests per minute per account. Requests are bounded to 32 KiB. OAuth endpoints have separate abuse limits. These are request limits, not a promise about available research credits.

For help, contact Margo with the client/version, tool name, time and non-sensitive error. Do not send access tokens, API keys or private prospect records.

1. Connect with OAuth and confirm that the five standard research tools are listed. Additional pipeline tools can be listed without being authorized.
2. Call get_margo_capabilities and get_usage_and_quota. These reads do not initiate paid research.
3. If you choose to spend research credits, agree a small search and its maximum first. Use one requestId, then poll the same job to its terminal state.
4. Check the delivered count, source evidence, limitations and actual account usage. A successful connection does not guarantee every requested contact field.
5. Disconnect from Connected AI agents and verify that access is rejected; reconnect when needed.

Client setup and availability can change. Refer to the current official guides for your client:

• Claude Code MCP guide
• Codex MCP guide
• OpenAI MCP authentication reference
• MCP authorization specification