AI Assistants (MCP)
Connect your AI assistant to Alhena so you can query your conversations, analytics, AI visibility, A/B experiments, and AI configuration directly — in plain English, without opening the dashboard.
Alhena exposes an MCP (Model Context Protocol) endpoint that AI assistants connect to as a custom tool server. Once authorized, your assistant can search conversations, pull performance metrics, inspect experiment results, review AI guidelines, check how visible your brand is in AI answers, and more.
Supported assistants: Claude (claude.ai and Claude Code), Codex, and ChatGPT.
Prerequisites
An active Alhena account
One of the supported assistants:
A Claude account at claude.ai, or Claude Code installed
Codex installed
A ChatGPT account with Developer mode enabled (see setup below)
Regions
Use the MCP URL that matches the region where your Alhena account is hosted:
US
https://app.alhena.ai/api/mcp
EU
https://eu.alhena.ai/api/mcp
If you are unsure which region you are on, check the URL you use to log in to Alhena. If it starts with eu.alhena.ai, use the EU endpoint; otherwise use the US endpoint.
Setup
Step 1: Add the custom connector
Click Add Custom Connector
Fill in the details:
Name: Alhena (or your preferred name)
MCP URL:
https://app.alhena.ai/api/mcp(US) orhttps://eu.alhena.ai/api/mcp(EU) — use the one matching your account's region
Click Add
Step 2: Authorize access
On the connector screen, scroll to the bottom and click Connect
An OAuth authorization screen will appear — click Allow Access to grant Claude permission to read your Alhena data
Step 3: Start using it
Open a new Claude chat and ask questions. Claude will automatically call Alhena when your question requires it.
Step 1: Add the MCP server
Run this command in your terminal, using the URL for your account's region:
US
EU
Step 2: Authorize access
Inside Claude Code, run:
Claude Code will detect that Alhena requires OAuth and automatically open your browser to an authorization page. Click Allow Access to complete the flow. Tokens are stored securely and refreshed automatically.
Step 3: Start using it
Ask questions in your Claude Code session. Claude will call Alhena automatically when your question requires it.
Step 1: Add the MCP server
Run this command in your terminal, using the URL for your account's region:
US
EU
Step 2: Authorize access
Log in to trigger the OAuth flow:
Codex will print an authorization URL. Open it in your browser and approve access on the consent screen.
Step 3: Verify the connection
You should see Alhena listed as enabled:
Restart Codex if the tools do not appear immediately.
Step 4: Start using it
Inside Codex, run /mcp to inspect connected MCP servers and confirm Alhena is active. Then ask questions — Codex will call Alhena automatically when your question requires it.
Step 1: Enable Developer mode
Click your profile icon and select Settings
In Settings, go to Security and login
Under Developer mode, toggle it on. ChatGPT will flag this as elevated risk — this is expected, since it allows adding connectors like Alhena that OpenAI hasn't independently verified
Step 2: Add the connector
Go to Settings > Connectors (this may also appear as Plugins) and click the + button
Fill in the New App details:
Name: Alhena (or your preferred name)
Server URL:
https://app.alhena.ai/api/mcp(US) orhttps://eu.alhena.ai/api/mcp(EU) — use the one matching your account's regionAuthentication: OAuth
Check I understand and want to continue to acknowledge the custom connector risk notice
Click Create
Step 3: Authorize access
Click Sign in with [connector name]
On the Alhena authorization screen, choose the organization to grant access to and click Allow access
Step 4: Start using it
Open a new ChatGPT chat and ask questions. ChatGPT will call Alhena automatically when your question requires it.
What you can ask
Conversations
"Find conversations where customers complained about shipping"
"Show me open escalated tickets from the past week"
"Pull up conversation 48291"
"Which conversations led to a purchase?"
Performance metrics
"How many AI vs human tickets did we have last month?"
"What's our CSAT trend over the last 30 days?"
"Show me ticket volume by day for the past two weeks"
"How are we performing compared to the previous period?"
CSAT by topic
"Which topics are driving our lowest CSAT ratings this month?"
"What's the CSAT score and average star rating for the Returns topic?"
"Show me the low-rated conversations about shipping delays"
A/B experiments
"What experiments are currently running?"
"Show me the results for experiment 12"
"Is experiment 7 statistically significant?"
AI configuration
"What guidelines does my AI follow?"
"Show me the guidelines for the answering agent"
"Why did the AI give this answer in ticket 48291?"
Conversation drivers
"What are the top pages driving conversations this month?"
"Which countries are our conversations coming from?"
AI Visibility
If you use AI Visibility, your assistant can pull that data too — how your brand shows up in AI-generated answers, who outranks you, and where to improve.
"How visible is my brand across AI search engines like ChatGPT and Google AI Overview this month?"
"Where do I rank against competitors in AI answers, and what should I focus on this week?"
"Which of our tracked prompts mention us, and which ones miss us in ChatGPT?"
"What did ChatGPT actually say when someone asked 'best waterproof hiking boots' — and which products did it show?"
"Which websites do AI engines cite in our space, and are we one of them?"
"Who beats us in AI answers, and what pages are they cited on that we aren't?"
"What behind-the-scenes searches do AI engines run where we don't rank?"
Troubleshooting
Connector fails to add (claude.ai)
Double-check the MCP URL matches your region: https://app.alhena.ai/api/mcp (US) or https://eu.alhena.ai/api/mcp (EU)
MCP server fails to add (Claude Code)
Ensure you have Claude Code installed and run the command exactly as shown, using the correct regional URL
MCP server fails to add (Codex)
Ensure you have Codex installed and run the command exactly as shown, using the correct regional URL
Can't find the connector option (ChatGPT)
Enable Developer mode in Settings > Security and login first — connectors to unverified servers like Alhena are hidden until it's on
OAuth authorization fails
Make sure you are logged into the correct Alhena account in your browser before clicking Allow Access
Browser doesn't open during OAuth (Claude Code)
Claude Code will display the authorization URL — copy it and open it manually
Claude doesn't use the connector
Open a new chat — existing chats may not pick up newly added connectors
ChatGPT doesn't use the connector
Open a new chat, and make sure the connector is enabled for that chat
Need to re-authorize (Claude Code)
Run /mcp and select "Clear authentication", then reconnect
Need to re-authorize (Codex)
Run codex mcp login alhena again to refresh the OAuth token
No data returned
Confirm your Alhena account has data for the time period or resource you are asking about
Related
Analytics — View performance data directly in the Alhena dashboard
AI Visibility — Track how your brand appears in AI-generated answers
A/B Testing — Set up and manage experiments
MCP Servers — Connect Alhena's AI agents to external MCP servers
Last updated