Coding agents and MCP

export HEYSTEFF_API_KEY=sk_live_...

npm install -g @heysteff/cli
heysteff login

You are going to integrate this project with heysteff, a messaging platform (WhatsApp, Instagram, Messenger, SMS and email) with a REST API.

Context
- heysteff workspace: <your workspace name> (slug: <slug>)
- API: https://app.heysteff.com/api/v1, with the header Authorization: Bearer $HEYSTEFF_API_KEY.
- The API key is already in the HEYSTEFF_API_KEY environment variable. Never write it in code, in a repository file or in this conversation.
- Docs for agents: https://app.heysteff.com/api/v1/llms-full.txt (read it before writing code), the spec at https://app.heysteff.com/api/v1/openapi.json and the rules in https://developers.heysteff.com/AGENTS.md.
- TypeScript SDK: @heysteff/sdk. CLI: @heysteff/cli (the heysteff command).

What I need
1. Inspect the repository: language, framework, how environment variables are handled and whether there is any messaging code already.
2. Propose the smallest step to send a real WhatsApp message and receive the reply in this project. Wait for my go-ahead before implementing it.
3. To send, use POST /v1/messages (in TypeScript, heysteff.messages.send) with an Idempotency-Key header.
4. To receive, create an endpoint for the message:received webhook: verify the X-Heysteff-Signature over the raw body, deduplicate by X-Heysteff-Delivery-Id and answer 2xx right away. The webhook secret goes in HEYSTEFF_WEBHOOK_SECRET.
5. To test the webhook locally, use heysteff webhooks trigger http://localhost:<port>/<path> --secret <secret>.
6. If the key starts with sk_test_, everything goes through the heysteff sandbox and you can only message the phones that joined the sandbox.

Do not invent endpoints or fields: if something is not in llms-full.txt, tell me.

I want to connect my own AI agent to heysteff so it answers my business customers on WhatsApp and the other connected channels. Act as my integration engineer and go step by step.

Context
- heysteff workspace: <your workspace name> (slug: <slug>)
- API: https://app.heysteff.com/api/v1, with the header Authorization: Bearer $HEYSTEFF_API_KEY.
- The API key is already in the HEYSTEFF_API_KEY environment variable. Never write it in code, in a repository file or in this conversation.
- Docs for agents: https://app.heysteff.com/api/v1/llms-full.txt (read it before writing code), the spec at https://app.heysteff.com/api/v1/openapi.json and the rules in https://developers.heysteff.com/AGENTS.md.
- TypeScript SDK: @heysteff/sdk. CLI: @heysteff/cli (the heysteff command).

Before writing code
1. Ask me what my business does, what the agent should handle on its own and when a person from the team has to step in.
2. Check access with heysteff whoami (or GET /v1/conversations?limit=1). Never ask me to paste an API key or a secret into this conversation: if one is missing, tell me how to set it in the environment variable.
3. Check whether a channel is already connected with heysteff conversations list --limit 5. If there is none, recommend connecting WhatsApp in the dashboard (Settings → Channels) or testing first with the sandbox and an sk_test_ key.
4. Inspect the repository and recommend the smallest setup. Wait for my go-ahead.

The integration
- An endpoint for the message:received webhook: verify X-Heysteff-Signature over the raw body, deduplicate by X-Heysteff-Delivery-Id, answer 2xx immediately and process in the background.
- The webhook already carries who to answer (channel, external_user_id and channel_connection_id) and bot_paused. When bot_paused is true, a person has the conversation: do not reply. Read the history with GET /v1/conversations/{id}/messages.
- Pass the history and my instructions to my model and reply with POST /v1/messages (heysteff.messages.send), with an Idempotency-Key derived from the received message so it never replies twice.
- The agent instructions live in a repository file, not inside the code: what the business does, the tone, what it can and cannot promise, and when to hand off to a person.
- Handoff to a person: when the agent does not know or should not continue, it tells the customer someone from the team will take over and calls POST /v1/conversations/{id}/escalate (heysteff.conversations.escalate) with the reason in reason. That pauses the bot, opens the case in the inbox and alerts my team; from then on events arrive with bot_paused set to true. When the team is done, the conversation comes back with POST /v1/conversations/{id}/bot and paused set to false, or with POST /v1/conversations/{id}/resolve. Do not keep that state on your side: read it with GET /v1/conversations/{id}. The key needs conversations:write.
- If the heysteff agent is on (Agent → Profile in the dashboard), turn it off before enabling yours, or both will reply.

Testing
- Test first with my own conversation: I message the number from my phone (or use heysteff webhooks trigger locally) and we review the reply.
- Do not reply to real customers without my explicit permission: keep replies limited to my test phone until I tell you to turn them on for everyone.

Do not invent endpoints or fields: if something is not in llms-full.txt, tell me.

/plugin marketplace add heysteff-com/agent-plugins
/plugin install heysteff@heysteff

npx skills add heysteff-com/agent-skills

mkdir -p ~/.claude/skills/heysteff && curl -fsSL https://developers.heysteff.com/skills/heysteff/SKILL.md -o ~/.claude/skills/heysteff/SKILL.md

claude mcp add --transport http heysteff "https://mcp.heysteff.com/mcp"

codex mcp add heysteff --url "https://mcp.heysteff.com/mcp"
codex mcp login heysteff

{
  "mcpServers": {
    "heysteff": {
      "url": "https://mcp.heysteff.com/mcp"
    }
  }
}