Skip to content

Get started with Heelo

Connect your AI app to Heelo in a few minutes. Then give it real work.

What is Heelo?

Heelo gives your AI app tools to do real work on the web and in your own accounts. Your AI app uses them through MCP, and your own code through the HTTP API.

Connect your AI app

Heelo CLI Coming soon

One command will sign you in and add Heelo to Claude Code, Codex and Cursor, with no API key to copy. Until then, add the MCP server below.

Add the MCP server

  1. Create a key in API keys in your dashboard and copy it at once: Heelo shows it only one time. Use one key for each app. The HTTP API uses the same key.
  2. Add these settings to your AI app. Field names can be different in each app.
FieldValue
Server nameHeelo
TransportHTTP (Streamable HTTP)
Server URLhttps://mcp.toolsprimitives.uk/mcp
HeaderAuthorization: Bearer YOUR_HEELO_API_KEY

In each example below, replace YOUR_HEELO_API_KEY with your key.

Claude Code

Run in your terminal:

claude mcp remove heelo --scope local 2>/dev/null; claude mcp remove heelo --scope user 2>/dev/null
claude mcp add --scope user --transport http heelo https://mcp.toolsprimitives.uk/mcp --header "Authorization: Bearer YOUR_HEELO_API_KEY"

Run this in a terminal, not inside Claude Code. It connects Heelo in every folder and replaces any earlier Heelo key. Then start Claude Code (quit and reopen it if it is already running) and run /mcp to check that Heelo is connected.

Codex

Run in your terminal:

mkdir -p ~/.codex && touch ~/.codex/.env && chmod 600 ~/.codex/.env && printf '\nHEELO_API_KEY=%s\n' 'YOUR_HEELO_API_KEY' >> ~/.codex/.env
codex mcp add heelo --url https://mcp.toolsprimitives.uk/mcp --bearer-token-env-var HEELO_API_KEY

Run this in a terminal, not inside Codex. It saves your key in Codex's own settings folder, so Codex finds it from any terminal, and running it again with a new key replaces the old one. Then start Codex (quit and reopen it if it is already running) and run /mcp to check that Heelo is connected.

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "heelo": {
      "url": "https://mcp.toolsprimitives.uk/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_HEELO_API_KEY"
      }
    }
  }
}

Open Cursor Settings → Tools & MCP and enable Heelo. Merge this entry with any existing servers.

Devin Desktop (Windsurf)

Add to ~/.config/devin/mcp_config.json:

{
  "mcpServers": {
    "heelo": {
      "url": "https://mcp.toolsprimitives.uk/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_HEELO_API_KEY"
      }
    }
  }
}

In Devin Desktop, open Customize → MCPs → This computer. You can open this file there and refresh the list. Merge this entry with any existing servers.

Other apps

Open API & Integration in your dashboard. It shows the setup for other MCP apps, and for Windows, with your key filled in.

Connect your accounts

Some tools work in your own account on another platform, for example your calendar or your LinkedIn profile. Connect each platform one time. Then every task can use it.

With a sign-in, you approve the access on the platform's own page. Security tells what Heelo keeps.

PlatformHow you connectTools
GoogleSign in with Googlegoogle.calendar_*
MicrosoftSign in with Microsoftoutlook_calendar.*mail.read_*
GitHubSign in with GitHubgithub.list_my_repos
NotionIntegration token from notion.so/my-integrationsnotion.*
Apple CalendarApple ID and an app-specific passwordapple_calendar.*
FastmailApp password with Mail accessmail.read_*
Other IMAP mailboxApp password: iCloud, Zoho, Yandex or your own servermail.read_*
LinkedInSign in on your own computerlinkedin.post
RedditSign in on your own computerreddit.post
InstagramSign in on your own computerinstagram.postinstagram.search
BlueskySign in on your own computerbluesky.post_browserbluesky.search
X (Twitter)Sign in on your own computer, or paste the auth_token and ct0 cookies in the dashboardtwitter.posttwitter.search_browser

Where Heelo asks you to connect

  1. Tools & Connections. Open Tools & Connections in your dashboard, select a platform and follow the steps.
  2. During a task. When a tool needs an account that you did not connect, it returns a connect link instead of a result. Open the link, connect the account, then ask your AI app to try again.
  3. Social accounts. Bluesky, LinkedIn, Reddit, Instagram and X open a browser on your own computer for the sign-in. Add the Heelo local login server to your AI app one time. Claude Code:
    claude mcp add heelo-local --env HEELO_API_KEY=YOUR_HEELO_API_KEY -- npx -y @heelo-ai/mcp-local
    In other apps, add an stdio MCP server with the command npx, the arguments -y @heelo-ai/mcp-local and the variable HEELO_API_KEY. Restart your AI app, then ask it to connect the account. When a sign-in expires, connect again in the same way.
  4. Your sender address for outreach e-mail. Add your own From address with outbound.mail.sender_add. Add the DNS records that it returns to your domain, then run outbound.mail.sender_verify. Heelo also sends a link to the mailbox that gets your replies. Open it to confirm that mailbox.

Try your first task

Your AI app cannot do this task alone, and it needs no other accounts.

1. Launch the page

Use Heelo to launch a landing page for my product, PR Notes: it turns merged pull requests into short release notes that users read. Make a share image with the line "Release notes your users read", publish the page with that image and an e-mail sign-up form, and give me a tracked short link to share.

2. Share the link, then ask for the numbers

How many people visited the page and signed up so far?

What happens

  1. media.render.card makes the share image, in the sizes for link previews, X and Instagram.
  2. inbound.page.publish publishes the page at a public URL, with the image and an e-mail sign-up form.
  3. inbound.link.wrap makes a short link that counts each click, with no cookies and no raw IP addresses.
  4. inbound.stats gives the visits, the unique visitors, the sign-ups and the sign-up rate. It gives the number of sign-ups, not their e-mail addresses.

Each publish of the page uses 25 credits. The image, the link and the numbers are free.

Acquisition workflow

Find customers and e-mail them from your own domain.

Before you start

  • A verified sender address on your own domain. See your sender address.
  • Your postal address. US law (CAN-SPAM) puts it in every e-mail. Your AI app asks you for it.
  • People in the US or Canada. Heelo refuses other countries.

Send this to your AI app

Use Heelo to find 20 US seed-stage developer-tool companies with 10 to 50 employees. Start an acquisition campaign to the CTO or the head of engineering at each company, one person per company. Send from my verified sender address. Write three short plain-text e-mails for days 0, 3 and 7 that offer a free trial of our API monitoring tool, with the tracking link in the first e-mail. Stop at the review and show me the people and the e-mails before anything is sent.

What happens

  1. Find companies. icp.search finds the companies in the background. 6 credits for each company.
  2. Find people and write the e-mails. acquisition.campaign.create finds the decision-maker at each company and prepares the sequence. 25 credits for each person found.
  3. Review. acquisition.campaign.status shows the people and the e-mails. Tell your AI app whom to remove.
  4. Approve. acquisition.campaign.approve shows the final draft first. Give your AI app the lawful basis for the e-mails and the approver's name. Only then does it send. 5 credits for each e-mail sent.
  5. Follow the results. acquisition.campaign.report shows sends, deliveries, clicks, replies and bounces. A reply stops the sequence for that person.

For 20 companies with one person each, the search and the lookups use up to 620 credits before the first e-mail goes out.

Reviews and approvals

Some tools stop before they write in your accounts, send e-mail or post. They show you what they will do and wait for your yes. Nothing is written, sent or posted before the approval.

How an approval works

  1. The tool stops at a review. Its status call returns what will happen, for example the values, the e-mails or the posts. It also returns a review_digest or a version for this review.
  2. Your AI app shows you the review. Read all of it.
  3. The approve call sends back the review_digest or the version unchanged, with the approver's name. If the content changed after you saw it, Heelo refuses, and your AI app shows you the new content.
  4. An approve call with a confirm field first shows what will happen and changes nothing. It acts only with confirm: true.

Who can approve

ToolsWhat waits for the approvalWho approves
doc.extract_fieldsdoc.review_decideA calendar or Notion write that uses the extracted values.You, or your AI app when you said that it can approve without showing you the values.
assistant.invoice.statusassistant.invoice.approveassistant.invoice.rejectThe payment reminder in your calendar, the record in Notion and the PDF receipt.You, or your AI app when you said that it can approve without showing you the values.
loop1.run.statusloop1.run.approveThe posts on your social accounts.Only you.
acquisition.campaign.statusacquisition.campaign.approveThe e-mails of the campaign.Only you. You also give the lawful basis for the e-mails.
validation.run.statusvalidation.run.approve_planvalidation.run.approve_contactsThe landing page, the e-mail sequence and the paid contact lookups (plan), then the e-mails (contacts).Only you. For the contacts, you also give the lawful basis.

For documents and invoices, your AI app shows you every value and asks if it is correct. It approves by itself only when you said explicitly that it can approve without showing you the values. A request to do the task is not that permission.

Check the values

With the values, doc.extract_fields and assistant.invoice.status return a notice: "AI can make mistakes. Check important info." Your AI app shows it to you. The PDF receipt of an invoice has the same notice.

Compare the values with the document before you approve. In a review, assistant.invoice.status gives invoice_document.link, a link that opens the invoice PDF for 24 hours. An invoice review stays open for 7 days. After that, the run fails, and you start a new run.

HTTP API

Use the HTTP API when your code knows which tool to run. Set HEELO_API_URL to https://toolsprimitives.uk and send your API key as a Bearer token.

List the tools

curl -s "$HEELO_API_URL/v1/tools" \
  -H "Authorization: Bearer $HEELO_API_KEY"

Each tool comes with its input_schema, its output_schema and its pricing: the price of one use in US dollars, so 0.25 is 25 credits. When pricing is null, see the tool in All tools.

Run a tool

Send POST /v1/tools/{tool_id}/invoke with the tool's input fields in {"input": {...}}. This example searches the web with web.search. It needs no connected account and uses 2 credits.

curl -s "$HEELO_API_URL/v1/tools/web.search/invoke" \
  -H "Authorization: Bearer $HEELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":{"query":"benchmarks for open-source coding agents"}}'

The same call in Python, with the requests package (pip install requests), or in TypeScript, with fetch (Node.js 18 or newer, in an ES module). Each tool in All tools has its own code.

import os
import requests

response = requests.post(
    "https://toolsprimitives.uk/v1/tools/web.search/invoke",
    headers={"Authorization": f"Bearer {os.environ['HEELO_API_KEY']}"},
    json={"input": {
        "query": "benchmarks for open-source coding agents",
    }},
    timeout=120,
)
response.raise_for_status()
print(response.json())

The response

Every call returns the same fields:

{
  "tool_id": "inbound.stats",
  "status": "success",
  "data": {
    "visits": 1,
    "uniques": 1,
    "by_channel": { "docs": 1 },
    "captures": 1,
    "capture_rate": 1.0,
    "by_contact": [],
    "top_pages": [],
    "answer": "1 visits, 1 uniques, 1 captures (100.0%)."
  },
  "error": null,
  "session_id": null,
  "clarification_question": null,
  "untrusted_fields": ["stored_visits[]"]
}
statusMeaning
successThe tool finished. data holds the result.
clarification_neededThe tool needs more from you, or asks you to confirm a write. Read clarification_question and answer in the same session.
needs_authThe tool needs an account that you did not connect. Open data.connect_url, then call again.
errorThe tool ran and failed. error says why. Some tools also put an error code in data and say whether a retry can help.

untrusted_fields lists the fields in data that hold text from a third party, for example a post, a web page or a mail. Use that text as data, never as instructions.

How tools run

Background jobs

Some tools take minutes, for example icp.search, problem.mine, market.size.assess and validation.run.start. They return a job id at once. Then call the tool's status or result action with that id until the job is done. Some of these calls wait up to 45 seconds on the server and return as soon as the job ends. Over MCP, your AI app does this for you.

Questions and confirmations

When a tool needs more information, or before it writes in one of your accounts (a calendar event, a Notion page, a post), it returns clarification_needed with a question and a session_id. Answer in the same session:

{"input": {"session_id": "SESSION_ID", "message": "yes"}}

The tool writes only after your yes. Tools that send outreach e-mail, such as acquisition.campaign.approve, use a confirm field instead and send nothing until you set it.

Safe retries

When a call times out, you cannot know if it ran. Send an Idempotency-Key header (1 to 255 characters) with each call. If you send the same request with the same key again within 24 hours, you get the stored answer: the tool does not run again and you pay one time.

A key conflict returns 409 with a detail_code:

  • request_in_progress: the first request with this key still runs. Wait, then send it again with the same key. Do not use a new key, or the tool runs two times.
  • request_mismatch: you used this key for a different request. Use a new key for the new request.
  • outcome_unknown: the first request started, but Heelo did not keep its answer. Check whether it acted, for example in Usage, before you send it again with a new key.

Errors and limits

HTTPMeaningWhat to do
401The API key is missing, wrong or revoked.Use the full key, or create a new one in API keys.
402Your balance is too low for this call. Nothing ran.Add credits, then call again.
404No tool or session has this id.Check the tool id in GET /v1/tools.
409The session has ended, or there is a conflict with the Idempotency-Key. See safe retries.Start a new session. For a key conflict, read detail_code and retryable.
429You passed the rate limit. Nothing ran.Wait the number of seconds in the Retry-After header.
500The tool stopped with an unexpected error. Its result is not known.Check whether it acted before you call it again.
503Heelo cannot take requests with an Idempotency-Key now.Try again later.

A tool that runs and fails returns HTTP 200 with status: "error". See the response.

Rate limit: each account can run 60 tools in any 60 seconds. Listing the tools, reading your balance and reading a session do not count.

Credits

  • Each tool has a fixed price in credits. All tools shows it.
  • Before a call runs, Heelo checks that your balance covers the most that the call can cost. Credits held for jobs that are not done do not count. If the balance is too low, the call returns 402 and nothing runs.
  • Heelo charges only for a call that succeeds, and only for what it produced. An empty search or a cancelled draft costs nothing.
  • A background job is charged when it is done. Reading its status or its result is free.

Read your balance

curl -s "$HEELO_API_URL/v1/billing/balance" \
  -H "Authorization: Bearer $HEELO_API_KEY"

balance_cents is what you can spend, in credits. See each call in Usage in your dashboard, and the plans in Pricing.

All tools

Each tool has its own page: what it does, its price, an example prompt, its input and output fields, and Python and TypeScript code that calls it. To find a tool, use the search box in the navigation.

Loop I: Distribution11 tools

Publish content: hosted pages, short links, share cards and visit statistics. The social posting tools are in Base tools.

  • inbound.page.publishPublish landing pages, articles, or changelogs on a Heelo-hosted site. Link to them from social posts and outreach emails.25 credits.
  • inbound.page.auditAudit a published page for performance and accessibility with Lighthouse.2 credits.
  • inbound.link.wrapCreate a short link and track clicks by campaign, channel, or contact without cookies.0 credits.
  • inbound.site.listList available publishing destinations and their status, including hosted sites, WordPress, Ghost, and Webflow.0 credits.
  • inbound.statsView campaign visits, visitors by channel and contact, lead conversion rates, and top pages.0 credits.
  • media.render.cardCreate social share images in multiple sizes for quotes, data, announcements, or covers.0 credits.
  • channel.expandAdapt a piece of content for different social platforms.0 credits.
  • loop1.run.startStart a distribution run that prepares a card, a page, and posts for each platform. Publishing follows approval.Charged by the tools it calls.
  • loop1.run.approveApprove a distribution run so its posts can be published.Charged by the tools it calls.
  • loop1.run.statusCheck the progress of a distribution run.0 credits.
  • loop1.run.stopStop a distribution run.0 credits.

Loop II: Acquisition32 tools

Find companies and people, send outreach e-mails, and run campaigns that connect these steps.

Loop III: Assistant32 tools

Read e-mail, get data from documents, make documents, and write to calendars and Notion.

Loop IV: Validation10 tools

Find the problems in a market, check if people pay to solve one, and test demand with a page and cold e-mails.

  • problem.mineFind complaints in a market and rank them by the number of people who mention them. The scan runs in the background and returns evidence links.800 credits.
  • market.size.assessLook for signs that people already pay to solve a problem, including paid alternatives and prices, hiring, outsourced work, and matching companies. Draft a landing page and cold emails in the background.800 credits.
  • scrape.structured.extractExtract rows from a public page and its subsequent pages using fields you specify.2 credits per page.
  • validation.run.startStart a validation run to find market problems, assess the top one, and draft a landing page and three cold emails.Charged by the tools it calls.
  • validation.run.statusAdvance a validation run by one step and show what comes next.Charged by the tools it calls.
  • validation.run.chooseChoose a different problem to assess.Charged by the tools it calls.
  • validation.run.approve_planRecord approval of the plan so Heelo can publish the page, create an email sequence, and find contacts. Your sender must be ready first: a verified sender on your own domain, with a From name, set as the default sender of that domain, and your postal address.Charged by the tools it calls.
  • validation.run.approve_contactsRecord approval of the contacts and the lawful basis for outreach so sending can begin.Charged by the tools it calls.
  • validation.run.senderView or save sender details, including the postal address and landing page site, and see whether sending is ready.0 credits.
  • validation.run.stopStop a validation run and cancel any company search in progress. Completed work is billed as usual.0 credits.

Base tools26 tools

Search, read web pages, research reports, send e-mail, post on social platforms and do tasks in a browser.

  • web.searchSearch the web and return titles, URLs, and snippets.2 credits.
  • web.fetchFetch a web page and return its text and a short summary.2 credits.
  • arxiv.searchSearch arXiv and return paper titles, authors, abstracts, and PDF links.2 credits.
  • github.searchSearch GitHub repositories.2 credits.
  • github.list_my_reposList repositories in the connected GitHub account, including private repositories.2 credits.
  • reddit.searchSearch Reddit posts.2 credits.
  • instagram.searchSearch Instagram posts by topic or account using the connected account.2 credits.
  • linkedin.searchSearch LinkedIn posts.2 credits.
  • bluesky.searchSearch posts using the connected Bluesky account.2 credits.
  • twitter.search_browserSearch posts using the connected X account.2 credits.
  • stock.get_quoteGet a live price quote for a stock, ETF, or cryptocurrency.2 credits.
  • trends.signalsCollect trending topics and keyword signals from social platforms and search.2 credits.
  • daily_paper.searchSearch Hugging Face Daily Papers.2 credits.
  • daily_paper.digestSummarize recent papers and send the digest by email or Slack.25 credits.
  • research.reportSearch the web, arXiv, GitHub, and Reddit to produce a research report with sources.25 credits.
  • stock.analyzeAnalyze a stock, ETF, or cryptocurrency and outline short-, medium-, and long-term scenarios. For research purposes.25 credits.
  • email.sendPreview an email and send it from the connected mailbox after confirmation.5 credits.
  • twitter.postPublish a post from the connected X account.40 credits.
  • linkedin.postPublish a post from the connected LinkedIn account.40 credits.
  • instagram.postPublish an image or video from the connected Instagram account.40 credits.
  • reddit.postPublish a post from the connected Reddit account.40 credits.
  • bluesky.post_browserPublish a post from the connected Bluesky account.40 credits.
  • web.fill_formFill out a web form, show a preview, and submit it after confirmation.40 credits.
  • kiwi.book_flightSearch for and book flights on Kiwi.com.40 credits.
  • booking_com.reserve_stayOpen a Booking.com reservation page and fill in the details up to the payment step.40 credits.
  • amazon.shopFind, compare, and recommend products on Amazon. Place an order on the connected account after confirmation.40 credits.

Security

  • Your API key gives full access to your account and its credits. Keep it out of code that you share. If it leaks, revoke it in API keys.
  • Heelo keeps the tokens and app passwords of your connected accounts encrypted. With a browser sign-in, Heelo keeps only the session cookies, never your password. Heelo never asks for a password or cookies in the chat.

Read the privacy policy for the data that Heelo keeps.

Troubleshooting

command not found: codex
Install the Codex CLI with the Codex setup guide. Then open a new terminal and run codex --version.
Your AI app does not show Heelo or its tools
Quit and reopen your AI app after each change to its settings. Then look for Heelo:
  • Claude Code and Codex: run /mcp in the app.
  • Cursor: open Cursor Settings → Tools & MCP, and check that Heelo is on.
  • Devin Desktop (Windsurf): open Customize → MCPs → This computer, and refresh the list.
If Heelo is not there, do the setup for your app in Connect your AI app again. For Claude Code and Codex, run the command in a terminal, not inside the app.
Heelo does not connect, or a tool fails with 401 or "unauthorized"
The key is wrong or revoked. Create a new key in API keys and put it where your app keeps it:
  • Claude Code and Codex: run the setup command again with the new key. It replaces the old key. Codex keeps the key in ~/.codex/.env (on Windows, %USERPROFILE%\.codex\.env).
  • Cursor and Devin Desktop: replace the key in the Authorization header of the Heelo entry in the JSON file.
HEELO_API_KEY is not set (Codex)
Codex reads the key from ~/.codex/.env each time that it starts. Run the Codex setup in Connect your AI app again, then quit and reopen Codex.
Heelo does not connect after you paste the URL
Use the plain server URL from Connect your AI app, not a Markdown link.
An HTTP error, for example 402 or 429
See errors and limits.
A long tool times out in your AI app
Ask your AI app to start the job and read the result later. See background jobs.