Margo

npx add-mcp 'https://www.margoleads.io/mcp'

Margo MCP documentation: Claude Code, Codex and ChatGPT AI agents & MCP

Connect an AI agent to Margo. Setup, OAuth permissions, five research tools, source inputs, credit limits, job results and troubleshooting.

Canonical: https://www.margoleads.io/docs/mcp

Connect your agent

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

• Where your account or workspace allows custom MCP apps, open its custom app/connection settings. Enable developer mode if required by your workspace.

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

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

Tools and permissions

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

.

Tool / scope	Arguments	Result and effect
get_margo_capabilities leads:read	None	Sources and account feature access, source geography, tariffs, result limits and caveats. No research credits.
get_usage_and_quota account:read	None	Plan, allowanceUsed, allowanceLimit, allowanceAvailable and purchasedCredits. Does not buy credits.
search_leads leads:search	Source inputs, requestId and maxCredits	Creates or resumes a durable research job. Uses existing credits; returns jobId, terminal, limitations, constraintCoverage and pollUrl.
get_search_status leads:read	{ "jobId": "…" }	Reads an owned job and its result. Does not start new research.
cancel_search leads:cancel	{ "jobId": "…" }	Cancels a queued or running owned job. Returns cancelled and jobId. Already delivered research may remain billable.

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.

Search inputs

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.

Input	Contract
source	google_maps, linkedin or shopify. Shopify is available only for enabled accounts; inspect capabilities first.
country	Uppercase two-letter country code, such as GB, US or AU. state is a region, not a country code.
category , keyword	Optional strings, 1–200 characters when supplied. Maps requires category. Shopify requires category or keyword.
city , state	Maps requires at least one. LinkedIn and Shopify use country targeting, not a guaranteed city filter.
geographyPolicy	strict (default) rejects city/state targeting for LinkedIn or Shopify. allow_country_broaden explicitly allows country-level research instead; disclose that broader scope.
minRating , maxRating	Maps only; numbers between 0 and 5. minRating cannot exceed maxRating.
noWebsite , noSocials , noEmail	Maps only; optional boolean filters. Inspect returned constraintCoverage for limits on enforcement.
linkedinParams	LinkedIn only: personTitle, seniority, industry, companyEmployeeSize and companyDomain. Each is an array of up to 30 strings (1–200 characters each). Country and count are derived from country and maxResults; this discovery action does not request separate email enrichment.
decisionMakerTitles , requiredChannels	Shopify only. Up to 30 role strings; requiredChannels accepts email, phone and/or linkedin (maximum 3). These are research constraints, not a promise every result has those fields.
requestId	8–160 characters: letters, digits, period, underscore, colon or hyphen. Unique per intended search; reuse it only for identical retries.
maxCredits	Required integer from 0 to 100000. Must cover the quoted maximum for the requested source/count; it is a safety cap, not a purchase.

Credits and retries

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.

Source	Credits per delivered record	Search minimum
Google Maps	1	23
LinkedIn person research	No additional per-lead discovery fee	Current server quote
Shopify	26	0

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

Pricing

. Margo MCP uses the existing account credit system; it does not add an agent subscription.

Jobs and results

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.

Authentication reference

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.

Purpose	Path
Protected resource discovery	/.well-known/oauth-protected-resource/mcp
Authorization server discovery	/.well-known/oauth-authorization-server
Dynamic client registration (DCR)	/api/mcp/oauth/register
Browser authorization and consent	/oauth/mcp/authorize
Token exchange and refresh	/api/mcp/oauth/token
Token revocation	/api/mcp/oauth/revoke

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

/dashboard/integrations/mcp

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.

API-key alternative

Developer clients supporting bearer authentication can use a Margo API key instead of OAuth. Create and revoke keys in

/dashboard/api-keys

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

/docs

REST API reference

and

/integrations/n8n

n8n guide

.

Troubleshooting

Symptom	What to check
401 / invalid token	Authenticate again. Check token expiry, revocation, the exact resource URL and canonical host. Do not use an MCP OAuth token as a REST key.
403 / access_denied	Verify your email and Professional or Business MCP eligibility. Browser consent must originate from Margo; an unapproved Origin is rejected.
insufficient_scope	Reconnect with the scope required by the tool. Capability/status reads need leads:read; quota reads need account:read.
invalid_arguments / city scope unsupported	Use the discovered schema: uppercase country code, correct source fields, Maps category/location and an explicit geography policy.
credit_limit_too_low	Read maximumCreditsRequired and current capabilities. Ask the user to agree the maximum; never silently raise their cap.
Unknown job / HTTP 404, or cancel HTTP 409	Use the jobId from the same account. A terminal job cannot be cancelled; do not start a new search to retrieve an old result.
429 / temporarily_unavailable / HTTP 503	Back off and inspect the error. Retry the same intended search with its existing requestId. Feature access does not guarantee provider availability. Contact support if it persists.
Tool missing in the agent	Confirm the connection is enabled in that session and its tools loaded. Check workspace custom-app permissions and current client version.
OAuth callback rejected	Use the canonical HTTPS Margo URL. Reconnect if the client has stale discovery metadata; issuer, resource and registered redirect must match exactly.

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

contact Margo

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

Check your connection

• Connect with OAuth and confirm that the five standard research tools are listed. Additional pipeline tools can be listed without being authorized.

• Call

• get_margo_capabilities

• and

• get_usage_and_quota

• . These reads do not initiate paid research.

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

• Check the delivered count, source evidence, limitations and actual account usage. A successful connection does not guarantee every requested contact field.

• Disconnect from Connected AI agents and verify that access is rejected; reconnect when needed.

Client references

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

https://code.claude.com/docs/en/mcp

• Claude Code MCP guide

https://developers.openai.com/codex/mcp

• Codex MCP guide

https://developers.openai.com/plugins/build/auth

• OpenAI MCP authentication reference

https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization

• MCP authorization specification