From companies to leads

The base URL is https://foundermcp.dev/api/v1. REST sends Authorization: Bearer gtk_…, with the key from API Access → API Keys. MCP is POST https://foundermcp.dev/api/v1/mcp with the same key. A missing, invalid or revoked key is 401 on every /api/v1 call, including while an API is closed. A valid key while the Company API or the Signals API is closed for your organization answers 404 on those routes. People search, people enrich and usage answer for every valid key.

Each step below is something you can say to the assistant, the tool that runs, and the REST call that does the same thing. Call preview_cost before a step that can spend credits. max_credits stops the call before the next row would pass the cap. A row that does not fit is left out and not charged.

1. Company

Say: "Look up Acme Analytics and use that company page."

MCP — lookup_company. Free.

{ "name": "lookup_company", "arguments": { "name": "Acme Analytics" } }

REST — GET /companies/lookup?q=Acme%20Analytics. Free. Only pages whose name matches.

Enriching that company (enrich with a company, or POST /company/enrich) is 1 credit when a company is found. Search companies is the same 1 credit per company on the page.

2. Signal or context

Say: "Who reacted to that company's posts in the last 30 days? Show me the cost first, then keep the finance leaders in Belgium."

MCP — preview_cost (free), then search_signals. Everyone who reacted or commented comes back as LinkedIn shows them: name, headline, what they did and the post. No AI judged them. A person is 5 credits. A search that finds nobody costs nothing.

{ "name": "preview_cost", "arguments": { "endpoint": "searches", "body": { "signal": { "type": "linkedin_engagement", "company": { "linkedin_url": "https://www.linkedin.com/company/acme-analytics" }, "leads_from": "reactors" }, "mode": "raw", "limit": 25, "max_credits": 125 } } }

{ "name": "search_signals", "arguments": { "signal": { "type": "linkedin_engagement", "company": { "linkedin_url": "https://www.linkedin.com/company/acme-analytics" }, "leads_from": "reactors" }, "limit": 25, "max_credits": 125 } }

Then the assistant judges: it reads each row's person.headline and the post_snippet of what they did, keeps the finance leaders in Belgium, and enriches only those (step 5). Recipes explains what a raw row holds.

To let FounderMCP judge instead, find_leads runs the same signal screened: our AI checks every person against a buyer profile. An exact lead is 20 credits. Someone just outside is 5 credits.

{ "name": "find_leads", "arguments": { "signal": { "type": "linkedin_engagement", "company": { "linkedin_url": "https://www.linkedin.com/company/acme-analytics" }, "leads_from": "reactors" }, "buyer_profile": { "roles": ["finance"], "levels": ["c_level"], "countries": ["BE"] }, "max_leads": 5, "max_credits": 100 } }

Both wait up to 25 seconds. If the search is still running, call get_search_results (raw) or find_leads (screened) again with search_id. The MCP POST sends Accept: application/json, text/event-stream.

REST — POST /searches/preview, then POST /searches with the same body and a required Idempotency-Key. Mode raw is the default: read the rows with GET /searches/{search_id}/results. With "mode": "screened" and a buyer_profile, read GET /searches/{search_id}/leads. The start answers 202 while the search runs. Poll GET /searches/{search_id} until succeeded.

If you already know the company and only want people in a role, skip the signal. Say "CFOs at this company in Belgium" and use the next step.

The other raw signals: a funding company is 1 credit, a technology company is 20, a person in a new role is 5. tech_adoption has no screened mode: take those companies into the next step.

3. People by role, seniority or department

Say: "At Acme Analytics, the CFOs in Belgium. Cap it at 15 credits."

MCP — preview_cost with endpoint leads, then company_leads. 5 credits per person. The ids are per_, not lead_.

{ "name": "company_leads", "arguments": { "companies": [{ "linkedin_url": "https://www.linkedin.com/company/acme-analytics" }], "filters": { "roles": ["CFO"], "seniority": ["c_level"], "departments": ["finance"], "countries": ["BE"] }, "limit": 3, "max_credits": 15 } }

REST — POST /leads/preview, then POST /leads with the same body. At least one of roles, seniority or departments is required. Seniority is c_level, vp, director or manager. Titles rank the rows. Seniority and countries exclude. One call is one page and returns at most 25 people.

A screened find_leads already returned qualified leads, and a raw person row from search_signals already is a person. Do not call company_leads for those.

4. Why this lead

Say: "Explain the first lead. Why them, and why now?"

MCP — explain_lead. Free. The id has to be a lead_ from find_leads or watch_signal. Do not pass a per_ id from search_signals or company_leads: a raw row carries its own why, in signals (the post, the comment, the round or the new role).

{ "name": "explain_lead", "arguments": { "lead_id": "lead_…" } }

REST — GET /leads/{lead_id}. Free. The body has the person, fit, why_now, and the evidence. links.people is the enrich URL. links.company is set when the company page is known and the Company API is open.

5. Enrich the contact

Say: "Find a work email for that lead. Do not look up a phone."

MCP — enrich. A profile is 2 credits. include_email: true adds 10 credits when an address is found. There is no phone argument. A work email and a phone together are the in-app contact reveal at 40 credits, not a field on this API.

For a lead_ id:

{ "name": "enrich", "arguments": { "lead_id": "lead_…", "include_email": true, "max_credits": 15 } }

For a per_ id from search_signals or company_leads, send person_ids instead of lead_id.

REST — POST /person/enrich with profile_urls or person_ids, and include_email. POST /person/enrich/preview is free. person_ids and max_credits are accepted only when the Signals API is open.

6. Outreach and the dashboard

Say: "Give me the dashboard link. Do not send anything."

The Signals API does not send the message. A tool result includes dashboard_url. It opens /en/gtm/leads or /en/gtm/signals for that search, watch, monitor or lead. REST responses do not include dashboard_url.

LinkedIn outreach goes through the assistant server (POST https://foundermcp.dev/api/mcp, key ejk_): your assistant writes the sequence and sends its own emails, FounderMCP sends the LinkedIn steps (start_linkedin_sequence, with a per_… or lead_… from this page). Nothing is sent until a person approves it, unless an admin turned on Autopilot. The tools, the limits and the approval rule are on Follow-up.

More copy-paste paths are on Recipes. The credit table is Credits & costs.