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
- 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.
- Add these settings to your AI app. Field names can be different in each app.
| Field | Value |
|---|---|
| Server name | Heelo |
| Transport | HTTP (Streamable HTTP) |
| Server URL | https://mcp.toolsprimitives.uk/mcp |
| Header | Authorization: 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_KEYRun 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.
| Platform | How you connect | Tools |
|---|---|---|
| Sign in with Google | google.calendar_* | |
| Microsoft | Sign in with Microsoft | outlook_calendar.*mail.read_* |
| GitHub | Sign in with GitHub | github.list_my_repos |
| Notion | Integration token from notion.so/my-integrations | notion.* |
| Apple Calendar | Apple ID and an app-specific password | apple_calendar.* |
| Fastmail | App password with Mail access | mail.read_* |
| Other IMAP mailbox | App password: iCloud, Zoho, Yandex or your own server | mail.read_* |
| Sign in on your own computer | linkedin.post | |
| Sign in on your own computer | reddit.post | |
| Sign in on your own computer | instagram.postinstagram.search | |
| Bluesky | Sign in on your own computer | bluesky.post_browserbluesky.search |
| X (Twitter) | Sign in on your own computer, or paste the auth_token and ct0 cookies in the dashboard | twitter.posttwitter.search_browser |
Where Heelo asks you to connect
- Tools & Connections. Open Tools & Connections in your dashboard, select a platform and follow the steps.
- 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.
- 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 runoutbound.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
media.render.cardmakes the share image, in the sizes for link previews, X and Instagram.inbound.page.publishpublishes the page at a public URL, with the image and an e-mail sign-up form.inbound.link.wrapmakes a short link that counts each click, with no cookies and no raw IP addresses.inbound.statsgives 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
- Find companies.
icp.searchfinds the companies in the background. 6 credits for each company. - Find people and write the e-mails.
acquisition.campaign.createfinds the decision-maker at each company and prepares the sequence. 25 credits for each person found. - Review.
acquisition.campaign.statusshows the people and the e-mails. Tell your AI app whom to remove. - Approve.
acquisition.campaign.approveshows 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. - Follow the results.
acquisition.campaign.reportshows 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
- 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_digestor aversionfor this review. - Your AI app shows you the review. Read all of it.
- The approve call sends back the
review_digestor theversionunchanged, with the approver's name. If the content changed after you saw it, Heelo refuses, and your AI app shows you the new content. - An approve call with a
confirmfield first shows what will happen and changes nothing. It acts only withconfirm: true.
Who can approve
| Tools | What waits for the approval | Who approves |
|---|---|---|
doc.extract_fieldsdoc.review_decide | A 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.reject | The 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.approve | The posts on your social accounts. | Only you. |
acquisition.campaign.statusacquisition.campaign.approve | The 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_contacts | The 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())// Node.js 18 or newer, in an ES module.
const response = await fetch("https://toolsprimitives.uk/v1/tools/web.search/invoke", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.HEELO_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
input: {
"query": "benchmarks for open-source coding agents"
},
}),
signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await 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[]"]
}| status | Meaning |
|---|---|
success | The tool finished. data holds the result. |
clarification_needed | The tool needs more from you, or asks you to confirm a write. Read clarification_question and answer in the same session. |
needs_auth | The tool needs an account that you did not connect. Open data.connect_url, then call again. |
error | The 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
| HTTP | Meaning | What to do |
|---|---|---|
401 | The API key is missing, wrong or revoked. | Use the full key, or create a new one in API keys. |
402 | Your balance is too low for this call. Nothing ran. | Add credits, then call again. |
404 | No tool or session has this id. | Check the tool id in GET /v1/tools. |
409 | The 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. |
429 | You passed the rate limit. Nothing ran. | Wait the number of seconds in the Retry-After header. |
500 | The tool stopped with an unexpected error. Its result is not known. | Check whether it acted before you call it again. |
503 | Heelo 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.
icp.searchFind companies that match an ideal customer profile. The job runs in the background and returns company, funding, and contact information.6 credits.icp.job_statusCheck the progress of an ICP search and retrieve its results.0 credits.icp.export_resultsExport completed ICP search results as CSV, JSON, or Markdown.0 credits.icp.cancel_jobStop an ICP search.0 credits.contact.resolveFind decision-makers at a company with email verification and sources.25 credits.demand.radarFind people discussing a specific pain point on the public web. Return one entry per person, with direct quotes, sources, and a 30-day trend.90 credits.outbound.mailManage outreach through the legacy action parameter. Use the dedicated outbound.mail tools for new integrations.0 credits.outbound.mail.sequence_createCreate an outreach sequence with 1 to 20 emails. Sending starts separately.0 credits.outbound.mail.sequence_enrollEnroll a contact in a sequence so the sending worker can deliver emails on schedule.5 credits per e-mail.outbound.mail.sequence_statusView a sequence and delivery status for each contact.0 credits.outbound.mail.sequence_listList the 100 most recent sequences.0 credits.outbound.mail.sequence_stopStop future emails in a sequence for a specific contact.0 credits.outbound.mail.sequence_resumeResume paused sending after the issue is resolved.0 credits.outbound.mail.contact_addAdd a contact who has agreed to be contacted and check their email address.0 credits.outbound.mail.contact_listList the 100 most recently added contacts.0 credits.outbound.mail.consent_recordRecord the lawful basis for emailing a contact.0 credits.outbound.mail.suppress_addAdd an email address to the suppression list.0 credits.outbound.mail.suppress_checkCheck whether an email address is on the suppression list.0 credits.outbound.mail.sender_addAdd a sender address on your own domain and get the required DNS records.0 credits.outbound.mail.sender_verifyCheck the DNS records and verification status for a sender address.0 credits.outbound.mail.sender_listList sender addresses and their status.0 credits.outbound.mail.sender_removeDisable a sender address.0 credits.outbound.mail.domain_checkCheck a sending domain's SPF, DKIM, DMARC, and related settings.0 credits.outbound.mail.reputation_statusView daily sending reputation, including sent emails, bounces, and complaints.0 credits.acquisition.campaign.createStart a campaign from a pain point or company list. Find decision-makers and draft up to five emails for approval.Charged by the tools it calls.acquisition.campaign.approveApprove a campaign and start sending its emails.Charged by the tools it calls.acquisition.campaign.statusCheck campaign progress and see the next step.0 credits.acquisition.campaign.reportView campaign results, including companies, contacts, sends, deliveries, clicks, replies, and bounces.0 credits.acquisition.campaign.listList the 50 most recent campaigns.0 credits.acquisition.campaign.pausePause prospecting and email sending for a campaign.0 credits.acquisition.campaign.resumeResume a paused campaign.0 credits.acquisition.campaign.cancelPermanently cancel a campaign.0 credits.
Loop III: Assistant32 tools
Read e-mail, get data from documents, make documents, and write to calendars and Notion.
mail.read_listList messages in a Microsoft 365, Outlook.com, or IMAP mailbox folder.2 credits.mail.read_getRead an email body and list its attachments.2 credits.mail.read_attachmentDownload an attachment from an email.2 credits.mail.read_watchFetch messages that arrived since the last check.2 credits.doc.extract_textExtract text and tables from PDFs, scans, Office files, or emails.25 credits.doc.extract_fieldsExtract fields such as invoice numbers, dates, amounts, and line items. Return the page and location of each value, and check the arithmetic.25 credits.doc.render_pdfTurn HTML into a PDF, such as an invoice, report, or receipt.25 credits.doc.render_docxGenerate an editable Word document.25 credits.doc.render_xlsxGenerate an Excel spreadsheet.25 credits.doc.review_decideApprove extracted data with optional corrections, or reject it.0 credits.assistant.invoice.startRead a PDF invoice attached to an email, extract and check its fields, and wait for review.Charged by the tools it calls.assistant.invoice.approveAfter approval, add a calendar payment reminder, create a Notion record, and generate a PDF receipt.Charged by the tools it calls.assistant.invoice.rejectReject an invoice workflow without creating any records.0 credits.assistant.invoice.statusCheck invoice workflow progress and see the next step. In review, it returns the values to check and a link that opens the invoice PDF for 24 hours.0 credits.assistant.invoice.listList the 50 most recent invoice workflows.0 credits.assistant.invoice.cancelStop an unfinished invoice workflow.0 credits.google.calendar_list_eventsList Google Calendar events within a date range.2 credits.google.calendar_create_eventCreate a Google Calendar event.5 credits.google.calendar_update_eventUpdate a Google Calendar event.5 credits.google.calendar_delete_eventDelete a Google Calendar event.5 credits.apple_calendar.list_eventsList Apple Calendar events within a date range.2 credits.apple_calendar.create_eventCreate an Apple Calendar event.5 credits.apple_calendar.update_eventUpdate an Apple Calendar event.5 credits.apple_calendar.delete_eventDelete an Apple Calendar event.5 credits.outlook_calendar.list_eventsList Outlook Calendar events within a date range.2 credits.outlook_calendar.create_eventCreate an Outlook Calendar event.5 credits.outlook_calendar.update_eventUpdate an Outlook Calendar event.5 credits.outlook_calendar.delete_eventDelete an Outlook Calendar event.5 credits.notion.read_pageRead the full contents of a Notion page.2 credits.notion.create_pageCreate a Notion page.5 credits.notion.update_pageRename a Notion page or append content.5 credits.notion.delete_pageMove a Notion page to the trash. It can be restored within 30 days.5 credits.
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
/mcpin 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.
- Claude Code and Codex: run
- Heelo does not connect, or a tool fails with
401or "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
Authorizationheader of the Heelo entry in the JSON file.
- Claude Code and Codex: run the setup command again with the new key. It replaces the old key. Codex keeps the key in
HEELO_API_KEY is not set(Codex)- Codex reads the key from
~/.codex/.enveach 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
402or429 - 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.