Connect Instagram to Codex with the HookSend MCP server
You connect Instagram to Codex by adding one [mcp_servers]table to Codex’s config.toml, pointing it at HookSend and sending a token in a header. Codex can then create campaigns, build DM flows and read your stats through 63 tools. Written on 30 September 2026.
How do I add an MCP server to Codex?
You add it to a TOML file. Codex reads its MCP servers from config.toml, one [mcp_servers.<name>] table per server, and a hosted server like HookSendneeds three things in that table: the address, the transport, and your token in an HTTP header. OpenAI’s configuration reference, read on 30 September 2026, documents both file locations.
The user-level file is ~/.codex/config.toml and applies everywhere you run Codex. A project can carry its own .codex/config.toml, which that same reference says is loaded only for projects you have marked trusted — worth knowing before you spend an afternoon wondering why a project-local file is being ignored. Put an Instagram connector in the user-level file: your Instagram account is not a property of one code repository.
Step 1
Create a HookSend token
Sign in to HookSend, open Settings and create an MCP token. The token is shown once, because only a fingerprint of it is stored, so copy it before you close the screen.
Step 2
Open Codex's config file
Open ~/.codex/config.toml, creating it if it is not there. OpenAI's configuration reference, read on 30 September 2026, documents that path for user-level settings and .codex/config.toml inside a project for settings that apply to that project only.
Step 3
Add one mcp_servers table
Add a table called [mcp_servers.hooksend] with url set to https://hooksend.app/api/mcp and an http_headers entry carrying Authorization = "Bearer YOUR_TOKEN". One table per server is the shape the reference documents.
Step 4
Restart Codex and ask it something
Restart Codex so it reads the file again, then ask what campaigns you have. An answer listing your campaigns means the token and the address are both right; an authentication error means the header is malformed or the token was revoked.
The block below is the shape OpenAI’s reference documents for a remote server, with HookSend’s address in it. Replace YOUR_TOKEN with the token you created, keeping the word Bearer and the space after it.
# ~/.codex/config.toml
[mcp_servers.hooksend]
url = "https://hooksend.app/api/mcp"
http_headers = { "Authorization" = "Bearer YOUR_TOKEN" }Already connected on hooksend.in? Leave it alone. That address still answers and is not being retired, so there is nothing to edit and no token to create again.
Is the Codex MCP config JSON or TOML?
TOML. Codex is the odd one out among AI clients here: most keep their MCP servers in a JSON file with a top-level mcpServers object, and Codex uses TOML tables instead. A JSON block pasted into config.toml does not parse, and Codex starts without the server rather than stopping to complain.
Two consequences worth stating, because both cost people an hour. The header line is an inline TOML table, so it is http_headers = {"Authorization" = "Bearer ..." } with an equals sign inside the braces, not the colon JSON uses. And the table name carries the server name: [mcp_servers.hooksend] is what makes the server appear as hooksend, so whatever you write after the dot is the name Codex will use when it talks about the tools.
Every field in the table below is named in OpenAI’s own Codex configuration reference, which we read on 30 September 2026. What each field is for, in the right-hand column, is our reading of that reference on that date rather than a quotation from it, and OpenAI can change any of this in a release without telling us — so check their reference if a field does not behave as described.
| Field in config.toml | Needed? | What it does for a HookSend connection |
|---|---|---|
| url | Required | The address of the MCP server. For HookSend that is https://hooksend.app/api/mcp, the same address every client uses. |
| http_headers | How the token travels | An inline table of HTTP headers sent with every request. HookSend authenticates on an Authorization header, so this is where your token goes if you keep it in the file. |
| bearer_token_env_var | Optional | Named in the same reference as the field that takes the name of an environment variable holding the token, rather than the token itself. Use it if you would rather your token never sat in a file. |
| env_http_headers | Optional | Headers whose values are read from environment variables. The other way to keep a secret out of config.toml. |
| enabled_tools / disabled_tools | Optional | Which of the 63 tools Codex may call. Listing only the read tools is how you give Codex a look at the account without letting it change anything. |
| startup_timeout_sec / tool_timeout_sec | Optional | How long Codex waits for the server to answer. Worth raising if you are on a slow connection and a first call times out. |
OpenAI’s reference documents more than these six fields, including OAuth options and per-tool approval modes. HookSend needs none of them: the connector authenticates on a token in a header, so the two lines above are the whole configuration.
What can Codex actually do with my Instagram account?
Run your automation, not just read it. Codex can create a comment-to-DM campaign on a reel, build a DM flow from a description, write a Comment Guard rule in plain words, reply inside an existing DM thread and read your stats and leads — 63 tools in all, the same ones the dashboard sits on top of. Codex is not being handed a reporting feed.
Four tool names, so you can check the claim rather than take it: campaigns_create makes a campaign, flows_create makes a DM flow, guard_rules_create writes a moderation rule and stats_overview reads the numbers. Codex is a terminal tool, which suits this better than it sounds: describing six campaigns in one prompt and having them exist is the kind of thing a person in a terminal actually wants, and a dashboard makes you click through six times.
Since 30 September 2026 the flow steps reachable this way include a wait of up to 24 hours, number and date comparisons, a jump into another flow, a rule for what happens when the same person enters a flow twice, and a notification when somebody reaches a step you care about. Campaigns can also answer comments up to 7 days old, which is the limit Meta sets on replying to a comment at all.
What will Codex refuse to do to my Instagram account?
Four things, and each is a real refusal rather than a promise. Codex cannot delete a campaign, a flow or a knowledge base, because no such tool exists. Codex cannot message somebody who has not messaged you, because Instagram does not allow it. Codex cannot spend money or change your billing. And 9 actions that cannot be undone refuse their first call and make Codex ask you.
Three limits belong to Meta rather than to HookSend, and Codex inherits all three. Meta allows one private reply per comment, ever, across every campaign and every tool, so a comment that has already had its reply cannot be answered again. Meta allows a reply inside a DM thread for 24 hours from that person’s last message. Meta allows a comment reply only within seven days of the comment. A connected Instagram account also has to be a professional account, which is Meta’s requirement for the API underneath all of this.
One more, because people assume the opposite: HookSendcannot read a DM thread nobody has written to you in, and cannot see messages sent before your account was connected. Codex asking to “summarise all my DMs” gets the conversations Instagram makes available to the connected account, not an archive.
Where these Codex steps come from
Both pages below are OpenAI’s, and every Codex fact on this page was read from them on 30 September 2026. OpenAI can change a file name, a field or a menu in any release, so if one of these now says something different, believe it rather than this page.
- Extending Codex with MCP
OpenAI's page for adding an MCP server to Codex, covering the CLI, the IDE extension and the config file, and the difference between a local process and a hosted server.
- Codex config file reference
Where config.toml lives, the mcp_servers table, and every field a remote entry takes, including the header and bearer-token options quoted above.
Questions people ask before they add it
- Is the Codex MCP config JSON or TOML?
- TOML. Codex reads its MCP servers from config.toml, not from a JSON file, which is the single most common mistake when someone copies a config across from another AI client. OpenAI's configuration reference, read on 30 September 2026, documents ~/.codex/config.toml for user-level settings and .codex/config.toml inside a project for that project alone. Each server is one [mcp_servers.<name>] table. A JSON block pasted into that file will not parse and Codex will start without the server rather than telling you loudly.
- Can Codex send an Instagram DM?
- Yes, through HookSend, and only in the one case Instagram allows. Instagram lets a business message somebody who messaged it first, so the inbox_send_reply tool can reply inside an existing thread and cannot start a new one. Meta's rule is a 24-hour window from that person's last message. Replying is also one of the 9 actions that refuse the first request and make Codex come back and ask you, because a DM cannot be unsent.
- Do I have to put my HookSend token in config.toml?
- No. OpenAI's reference, read on 30 September 2026, documents bearer_token_env_var and env_http_headers alongside http_headers, and both take the name of an environment variable rather than the secret itself. Either one keeps the token out of a file that often sits in a dotfiles repository. Whichever you choose, HookSend stores only a SHA-256 fingerprint of the token, so a token lost from your side cannot be read back from ours, and revoking it in Settings stops it working immediately.
- Does this work in the Codex IDE extension as well as the CLI?
- Yes. OpenAI's reference, read on 30 September 2026, documents the same mcp_servers surface for the CLI and the IDE extension, and describes adding a server in the extension through the gear menu, then MCP servers, then Add server, choosing Streamable HTTP for a hosted server like this one. The address and the token are the same either way. Among the clients this site documents, Codex is the one that keeps its MCP servers in TOML; ChatGPT, Claude and Antigravity each hold the same three details somewhere else.
- What can Codex not do to my Instagram account through HookSend?
- Codex cannot delete a campaign, a flow or a knowledge base, because HookSend publishes no tool that deletes one — where the dashboard can delete, the connector offers pause or archive instead. Codex cannot start a DM with somebody who has not messaged you, because Instagram does not allow it. Codex cannot buy anything, change your billing, invite a colleague or mint another token: those four refuse an AI client outright and stay with a person who is signed in.
- Which HookSend plan do I need to use Codex with my Instagram account?
- The 15-day trial or any paid plan. The connector is not part of the Free plan, so a workspace that has finished its trial and moved to Free cannot connect Codex until it upgrades. Paid plans start at $3.50 a month (₹99 in India). Everything Codex does counts against the same monthly DM allowance and AI credits as the dashboard, so the connector is not a way around a plan limit.
- Will Codex do something to my account without asking me?
- Not the things that cannot be undone. 9 actions refuse their first call outright and tell Codex to check with you before repeating it, which is enforced by HookSend rather than by asking the model politely. A new flow is saved unpublished and a new Comment Guard rule is saved switched off. A campaign is the exception and worth knowing: like one built in the dashboard it goes live as soon as it is created, unless it is asked for paused.
Read next
Try it on the trial before you pay
15 days of every feature, no card, and the connector is included, so Codex can be running your automation on day one. After the trial the Free plan covers 2,500 DMs a month on 1 Instagram account but does not include the connector; paid plans start at $3.50 a month (₹99 in India).
Start free