MCP Connection and Access Management

What you’ll do

MCP allows a compatible client to use Hanna actions as clearly defined tools. Connection is established via OAuth, so there is no need to copy an API key into the chat or the MCP client settings.

Before You Begin

API and MCP access granted by an administrator is required. Grant only the specific access needed for the integration and do not use personal keys for shared company integrations.

Before Connecting

Ensure that:

• the user account can log in to the required Hanna account;
• the user's role allows viewing and modifying the necessary modules;
• API and MCP access has been granted in the administrator settings;
• you are using a trusted MCP client.

How to Connect Hanna to an MCP Client

1. Initiate the connection to a new remote MCP server within your MCP client.
2. Specify the server address: https://mcp.hannacrm.app/mcp.
3. When the client opens the Hanna login screen, enter your account name. This is the subdomain part before .hannacrm.app, not the full web address.
4. Log in to your Hanna account.
5. Review the requested access and confirm only if you recognize both the MCP client and the account.
6. Return to the client and verify that the Hanna tools are displayed.

If your MCP client is ChatGPT, follow Connecting Hanna CRM to ChatGPT for the complete plugin creation, installation, OAuth authorisation, and first safe test sequence.

Where to view available tools

Open System Settings → API and MCP and click MCP Documentation. The documentation is available at:

https://{your-account}.hannacrm.app/mcp/docs

It categorizes tools by CRM modules and directories. For each tool, the documentation specifies its purpose, available parameters, and fields. For example, a module might include tools for searching, retrieving a single record, creating, and updating. Some directories are intended solely for search operations.

The documentation outlines what "Hanna" can provide to MCP clients; however, the data actually accessible is limited by the settings of the logged-in user and the account configuration.

The API documentation section at the top of the Help Center is for REST API v4 and does not list MCP tools. Always use your account's /mcp/docs page for the MCP technical reference.

How to use MCP safely

Before confirming an action, review which module and record the client intends to modify. Actions such as creation, editing, or other data modifications may trigger standard "Hanna" automation rules, notifications, and updates to related records.

If the client only requires information retrieval, do not grant broader access permissions solely for the sake of MCP. It is preferable to use a dedicated user account or a role with strictly limited module access, provided this aligns with your access management policies.

If the MCP client fails to connect

1. Check the server address: https://mcp.hannacrm.app/mcp.
2. Ensure you have specified the correct account subdomain.
3. Sign in to Hanna in your browser and verify that the team member's account is active.
4. Check API and MCP access for team member, as well as the permissions module.
5. Restart the OAuth connection process from the MCP client.
6. Verify the names and parameters of available tools against the MCP Documentation.

If the connection works but a specific tool fails to return data or prevents modifications, you should typically check the team member role, module permissions, record visibility, and mandatory fields.

If MCP still fails to connect or a specific tool does not work after these checks, send Hanna Customer Support your company's Hanna address, MCP client name and version, attempt time and time zone, the step or tool name, and the exact error text. Do not send passwords, OAuth codes, or other sign-in credentials.

Related articles

• Connecting Hanna CRM to ChatGPT
• API and MCP Settings and Documentation