> For the complete documentation index, see [llms.txt](https://humanic.gitbook.io/humanic/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://humanic.gitbook.io/humanic/getting-started-with-humanic/humanic-mcp-server.md). # Humanic MCP Server ## Humanic MCP Server Humanic exposes its capabilities through an MCP (Model Context Protocol) server, allowing you to connect Humanic directly to AI tools, agents, and workflows. This means you can trigger Humanic campaigns, access your data, and automate email workflows from within any MCP-compatible environment — including Claude, Cursor, and other AI-native tools. *** ### What is the Humanic MCP server? MCP is an open protocol that lets AI models and agents communicate with external tools and services in a standardized way. The Humanic MCP server acts as a bridge between your AI environment and your Humanic account — giving external tools full organizational access to create, manage, and trigger Humanic campaigns programmatically. In practical terms, this means you can build AI workflows that use Humanic as an execution layer. Instead of logging into the Humanic dashboard manually, an AI agent in your environment can communicate directly with Humanic and act on your behalf. *** ### Authentication (OAuth recommended) You can connect in two ways: 1. **OAuth (recommended)** — If your MCP client supports OAuth (for example Claude), use that. You sign in with your Humanic account; no API key to copy, store, or rotate. Prefer this whenever the client offers it. 2. **API key** — Works in any MCP client. Create a key on the API Keys page and send it as a Bearer token. **Server URL** (same for both methods): ``` https://mcp.humanic.ai/mcp ``` **API key authorization header** (only when not using OAuth): ``` Bearer YOUR_API_KEY ``` Replace `YOUR_API_KEY` with an active API key from your Humanic account. The server URL is also shown on the [API Keys](https://app.humanic.ai) page in the dashboard. *** ### How to generate an API key Use this only if your client does not support OAuth, or you prefer key-based auth. **Step 1 — Open your account menu** Click your profile avatar in the bottom left corner of the Humanic dashboard. A menu will appear with options including Manage account, Domains Settings, Manage Subscriptions, API Keys, and Sign out. **Step 2 — Go to API Keys** Click API Keys. This opens the API Keys page where you can view existing keys and create new ones. **Step 3 — Create a new key** Click the + New Key button in the top right corner. Give your key a descriptive name — for example, "Claude Integration" or "Cursor Workflow" — so you can identify it later. Click confirm to generate the key. **Step 4 — Copy and store your key immediately** Your API key is shown in plaintext only once. Copy it immediately and store it securely — in a password manager, a secrets vault, or your environment's secure configuration. Once you leave the page, the plaintext value cannot be retrieved again. If you lose it, you will need to deactivate the old key and generate a new one. **Step 5 — Use the key in your MCP connection** Paste the key into the authorization header wherever you are configuring the MCP connection, formatted as: `Bearer YOUR_API_KEY`. *** ### Connecting Humanic MCP to Claude If you are using Claude as your AI environment, you can connect the Humanic MCP server so Claude can interact with your Humanic account. **Prefer OAuth** when Claude offers it for this server — complete the sign-in flow in the client instead of pasting an API key. If you use an API key instead, add the following in your Claude MCP configuration: **Name:** Humanic **Server URL:** `https://mcp.humanic.ai/mcp` **Authorization header:** `Bearer YOUR_API_KEY` Once connected, Claude will be able to use Humanic's tools natively within conversations — letting you prompt Claude to create campaigns, query audience data, or trigger actions in Humanic without leaving your AI workspace. *** ### Connecting Humanic MCP to Cursor If you are using Cursor or another MCP-compatible coding environment, add the Humanic MCP server to your tool configuration. Use OAuth when the client supports it; otherwise use the server URL and a Bearer API key. Check your tool's MCP documentation for the specific configuration format, then plug in the Humanic server URL and (if needed) your API key. *** ### Managing your API keys Your API Keys page shows all active keys along with their creation date, expiration date, and last used timestamp. Each key expires one year from creation. **Renaming a key** — Click the pencil icon next to any key name to rename it. Use names that clearly identify where the key is being used, such as "Claude Production" or "Internal Automation." **Deactivating a key** — Click Deactivate next to any key to revoke its access immediately. Do this if a key is no longer in use, has been exposed, or belongs to a workflow you are retiring. You can Activate the key again later if needed. **Deleting a key** — Click the trash icon to permanently delete a key from your account. *** ### Security best practices API keys grant full organizational access (MCP and REST APIs such as unsubscribe sync). Treat them with the same care as passwords. Prefer OAuth for MCP when available so you are not managing long-lived secrets in every client. Never paste an API key directly into source code, commit it to a repository, or share it in plain text over chat or email. Use environment variables or a secrets management tool to store and inject keys in any automated workflow. Create one key per integration rather than reusing the same key across multiple tools. This way, if one key needs to be revoked, your other integrations remain unaffected. Regularly review your API Keys page and deactivate any keys that are no longer active or that show unexpected usage patterns. The Last used timestamp on each key makes it easy to identify keys that are idle or unrecognized. *** ### Frequently asked questions **Should I use OAuth or an API key for MCP?** Use OAuth when your client supports it — it is the recommended option. Use an API key when the client only supports header-based auth, or for non-MCP REST integrations (for example unsubscribe sync). **How many API keys can I create?** There is no stated limit. You can create as many keys as you need — one per integration is the recommended approach. **What happens when a key expires?** Keys expire one year from their creation date. Once expired, any integration using that key will lose access. Generate a new key and update your configuration before the expiration date to avoid disruption. **Can I see what actions a key has performed?** The Last used field on the API Keys page shows the most recent time a key was used. For detailed activity logs, contact Humanic support. **What level of access does an API key grant?** Each key grants full organizational access. There are no scoped or read-only key options at this time — treat every key as having full permissions. **What should I do if a key is compromised?** Deactivate it immediately from the API Keys page and generate a new one. Update all integrations using the compromised key with the replacement as quickly as possible. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://humanic.gitbook.io/humanic/getting-started-with-humanic/humanic-mcp-server.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.