> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hookmyapp.com/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP
> Connect HookMyApp to MCP-capable tools and work your Facebook Page from an agent.
Endpoint:
```text theme={null}
https://api.hookmyapp.com/mcp
```
## Authentication
Choose the auth option your MCP client supports, in this order:
1. **HookMyApp CLI**: `hookmyapp agent setup` configures the server in every coding agent installed on your machine: Claude Code, Codex, and Cursor.
2. **Sign in from your MCP client**: add the server by URL and sign in when prompted (for example `/mcp` in Claude Code). No API key needed.
3. **API key**: create an API key in HookMyApp and pass it as a header. Best for CI and headless environments.
Accepted API key headers:
```http theme={null}
Authorization: Bearer hmok_...
```
```http theme={null}
X-API-Key: hmok_...
```
Use `Authorization: Bearer` for bearer-token clients. Use `X-API-Key` when your MCP client lets you configure custom headers.
## Connect
### HookMyApp CLI
```bash theme={null}
hookmyapp agent setup
hookmyapp doctor
```
Configures Claude Code, Codex, and Cursor, and installs the HookMyApp agent skills. Needs CLI 0.14.19 or newer.
Add `--client claude`, `--client codex`, or `--client cursor` to set up only one of them.
The credential is written into each entry, so no client needs a separate sign-in. Setup prints one line per client naming the restart it needs.
MCP tools load when a session starts, so restart your agent after running this. Until then, every operation works through the `hookmyapp` CLI.
### Sign in from your client
```bash theme={null}
claude mcp add --transport http hookmyapp https://api.hookmyapp.com/mcp
```
Run `/mcp`, pick `hookmyapp`, and approve the sign-in in your browser. Codex and Cursor support the same flow with their own commands.
### API key
Set your HookMyApp API key:
```bash theme={null}
export HOOKMYAPP_API_KEY="hmok_..."
```
```bash Codex theme={null}
codex mcp add hookmyapp --url https://api.hookmyapp.com/mcp --bearer-token-env-var HOOKMYAPP_API_KEY
```
```bash Claude Code theme={null}
claude mcp add --transport http hookmyapp https://api.hookmyapp.com/mcp \
--header "Authorization: Bearer $HOOKMYAPP_API_KEY"
```
```json Cursor theme={null}
{
"mcpServers": {
"hookmyapp": {
"url": "https://api.hookmyapp.com/mcp",
"headers": {
"Authorization": "Bearer ${env:HOOKMYAPP_API_KEY}"
}
}
}
}
```
### Use X-API-Key instead
Codex CLI has no `--header` flag, so `X-API-Key` goes in `~/.codex/config.toml`. For Cursor and Claude Code, swap the header.
```toml Codex theme={null}
[mcp_servers.hookmyapp]
url = "https://api.hookmyapp.com/mcp"
env_http_headers = { "X-API-Key" = "HOOKMYAPP_API_KEY" }
```
```bash Claude Code theme={null}
claude mcp add --transport http hookmyapp https://api.hookmyapp.com/mcp \
--header "X-API-Key: $HOOKMYAPP_API_KEY"
```
```json Cursor theme={null}
{
"mcpServers": {
"hookmyapp": {
"url": "https://api.hookmyapp.com/mcp",
"headers": {
"X-API-Key": "${env:HOOKMYAPP_API_KEY}"
}
}
}
}
```
## Tools
Facebook Page tools. Every tool takes `channelId`, the `ch_` id of a Facebook channel.
| Tool | Input | Output |
| ----------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `list_facebook_conversations` | `cursor?` | `conversations[]` (`id`, `participantId`, `participantName`, `updatedAt`, `unreadCount`, `snippet`), `cursor.next` |
| `list_facebook_posts` | `cursor?` | `posts[]` (`id`, `message`, `createdAt`, `permalink`, `type`), `cursor.next` |
| `publish_facebook_post` | `kind` (`text`, `link`, `photo`, `video`, `reel`), `message?`, `link?`, `mediaUrl?`, `description?` | `postId` (`{pageId}_{id}`), `mediaId` (videos and reels), `kind` |
| `delete_facebook_post` | `postId` | `postId`, `deleted` |
| `list_facebook_comments` | `postId`, `cursor?` | `comments[]` (`id`, `fromName`, `message`, `createdAt`, `isHidden`, `parentId`), `cursor.next` |
| `reply_facebook_comment` | `commentId`, `message`, `private?` | `commentId`, `private`, `replyId` (public) or `messageId` (private) |
| `moderate_facebook_comment` | `commentId`, `action` (`hide`, `unhide`, `delete`) | `commentId`, `action`, `ok` |
| `get_facebook_insights` | `postId?`, `metrics?`, `period?` (`day`, `week`, `days_28`) | `target` (`page` or `post`), `metrics[]` (`name`, `period`, `values[]` with `value`, `endTime`) |
| `get_facebook_page` | none beyond `channelId` | `pageId`, `name`, `category`, `followers`, `link`, `pictureUrl` |
Shared tools that understand Facebook channels:
| Tool | Use it for |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `status` | Check auth, organization, scopes, and next steps. Also returns unacknowledged `notifications[]` |
| `list_channels`, `get_channel` | Facebook rows carry `facebookPageName` and `facebookPagePictureUrl`; `get_channel` adds `linkedInstagramChannelId` when the Page has a connected Instagram account |
| `send_message` | Send a Messenger message: `recipient.id` is the PSID from the webhook or the conversation list |
| `create_onboarding_link` | `channelType: "facebook"` mints a link that connects a customer's Page, and its linked Instagram account, into the target workspace |
| `start_sandbox_session` | `channelType: "facebook"` returns the bind code and an `m.me` deep link to the sandbox Page |
| `get_webhook_config`, `set_webhook_destination`, `clear_webhook_destination`, `get_hmac_secret`, `rotate_hmac`, `set_forwarding`, `list_deliveries`, `get_delivery` | Same as for every channel type |
The Instagram tools (`publish_instagram_media`, `list_instagram_comments`, `get_instagram_insights` and the rest) work on an Instagram channel connected through a Page too. See [Instagram MCP](/instagram/mcp-server).
If a tool asks you to reconnect the channel, [reconnect](/facebook/connect#reconnect) once from the dashboard.
## Examples
Ask your agent to check setup:
```text theme={null}
Use HookMyApp MCP to check my organization status and tell me the next action.
```
Ask your agent to read the inbox:
```text theme={null}
Use HookMyApp MCP to list the unread Messenger conversations on Facebook channel ch_xxxxxxxx and draft a reply to each.
```
Ask your agent to publish a post:
```text theme={null}
Use HookMyApp MCP to publish https://example.com/photo.jpg to Facebook channel ch_xxxxxxxx with the message "New drop".
```
Ask your agent to work the comment section:
```text theme={null}
Use HookMyApp MCP to list the comments on my latest Facebook post, reply to questions, and hide spam.
```
Ask your agent for the numbers:
```text theme={null}
Use HookMyApp MCP to read this week's Page insights on Facebook channel ch_xxxxxxxx.
```
## Project MCP vs docs MCP
| Server | Endpoint | Use it for |
| ----------- | ------------------------------- | -------------------------------------------------------------------- |
| Project MCP | `https://api.hookmyapp.com/mcp` | Operating HookMyApp with the CLI-configured credential or an API key |
| Docs MCP | Not published yet | Documentation lookup only |
Use the [CLI](/facebook/cli) when your agent has terminal access. Use MCP when your agent supports MCP and should operate HookMyApp directly.