Connect Hawkscan to your AI agent
Last updated · By Hawkscan
Add Hawkscan as a remote MCP server in Claude, Claude Code, ChatGPT or any other agent that supports MCP, sign in with your Hawkscan account and approve the connection. Your agent can then read and update your AI visibility data.
Before you start
- A Hawkscan account with an active paid plan or a trial in progress.
- Claude, Claude Code, ChatGPT or any other agent that supports remote MCP servers.
You sign in once, in your browser. There is no API key to create.
Server address
Every agent connects to the same address.
https://hawkscan.ai/mcpAdd Hawkscan to your agent
- Open Settings, then Connectors.
- Click Add custom connector.
- Name it Hawkscan and paste the server address.
- Click Connect, then sign in to Hawkscan when you are redirected.
- Run this command in your terminal.
claude mcp add --transport http hawkscan https://hawkscan.ai/mcp
- Start Claude Code, type
/mcp, select hawkscan and choose Authenticate. - Sign in to Hawkscan in the browser window that opens.
Add --scope user to use Hawkscan in all your projects.
- Open Settings, then Apps & Connectors.
- In Advanced settings, turn on Developer mode.
- Click Create, name it Hawkscan, paste the server address and choose OAuth.
- Confirm, then sign in to Hawkscan when you are redirected.
Hawkscan is not in the ChatGPT directory yet, so you add it as a custom connector. Availability depends on your ChatGPT plan.
Hawkscan is a standard remote MCP server. Any agent that supports remote MCP servers and OAuth sign-in connects with these settings.
| Setting | Value |
|---|---|
| Server address | https://hawkscan.ai/mcp |
| Transport | Streamable HTTP. Some agents call it HTTP or Remote. |
| Authentication | OAuth. Your agent registers itself, so leave the client ID, client secret and API key empty. |
If your agent has a settings screen
- Find where your agent adds MCP servers. It may be called Tools, Connectors or Integrations.
- Add a remote server, name it Hawkscan and paste the server address.
- If you are asked, choose Streamable HTTP and OAuth.
- Start the connection, then sign in to Hawkscan in your browser and approve.
If your agent uses a configuration file or a command
Add this to ~/.cursor/mcp.json, or to .cursor/mcp.json in a project.
{
"mcpServers": {
"hawkscan": {
"url": "https://hawkscan.ai/mcp"
}
}
}Then open the MCP section of Cursor's settings and sign in to Hawkscan.
Add this to .vscode/mcp.json in your workspace, or to the mcp.json of your user profile.
{
"servers": {
"hawkscan": {
"type": "http",
"url": "https://hawkscan.ai/mcp"
}
}
}Start the server. VS Code opens your browser so you can sign in to Hawkscan.
Add this to ~/.gemini/settings.json.
{
"mcpServers": {
"hawkscan": {
"httpUrl": "https://hawkscan.ai/mcp"
}
}
}In Gemini CLI, run /mcp auth hawkscan to sign in.
Run this command in your terminal.
codex mcp add hawkscan --url https://hawkscan.ai/mcp
Sign in to Hawkscan in the browser window that opens. If none opens, run codex mcp login hawkscan.
If your agent only runs local servers
Use the mcp-remote bridge, which needs Node.js. Your agent starts it locally, and the bridge connects to Hawkscan and handles the sign-in.
{
"mcpServers": {
"hawkscan": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://hawkscan.ai/mcp"
]
}
}
}Hawkscan does not issue API keys. An agent that cannot sign in with OAuth, directly or through the bridge, cannot connect.
Approve the connection
Hawkscan shows which app is asking for access and where it will return. Approve to finish. Without an active paid plan, the connection stops at this screen.
Connect Claude to Hawkscan
This app is asking to access your Hawkscan account.
- It will return to
- claude.ai
- Signed in as
- you@company.com
- Full access
- It will read all the data of your organization and can change it: add prompts and competitors, update actions, delete prompts and competitors.
Try it
Open a new conversation and ask:
- Which projects do I have in Hawkscan?
- How did my visibility change this week against Confluence?
- Which sources do AI assistants cite instead of me?
- What should I do first on my action plan?
- With a coding agent: fix the top action of my plan, then mark it as done.
What your agent can do
Your agent gets 16 tools. Data tools filter by project and, where it applies, by period and model, as in the app.
| Tool | What it does |
|---|---|
| Read | |
List projectslist_projects | Projects of your organization, with brand and country |
Get brand visibilityget_visibility | Visibility of your brand, its trend and the detail by model |
List competitorslist_competitors | Your ranking against competitors |
List promptslist_prompts | Tracked prompts, categories and metrics |
Get a promptget_prompt | Model answers, brands and sources cited, by date |
List prompt suggestionslist_prompt_suggestions | Suggested prompts waiting for a decision |
List responseslist_responses | Model answers across a project, newest first |
List sourceslist_sources | Domains and pages cited |
List actionslist_actions | Your action plan, with the status and impact of each action |
Get an actionget_action | Why it matters, what to do, the page to change and the competitors cited there |
| Change | |
Update an action statusupdate_action_status | Moves an action to todo, in progress, done or archived. Free and reversible. |
Add promptsadd_prompts | Starts their first analyses, within your plan's prompt quota. A batch that would exceed it is refused. |
Add competitorsadd_competitors | Recomputes the brands found in your stored answers, at no analysis cost. |
| Delete | |
Remove competitorsremove_competitors | Deletes their detections and keeps your answers. Adding one back rebuilds its history. |
Delete promptsdelete_prompts | Permanent. Your agent shows you what would be deleted, then confirms with a code valid for 5 minutes. |
Delete a projectdelete_project | Deletes nothing by itself. Returns a link to a confirmation you validate in Hawkscan. |
Access and security
- Your agent only sees the data of your organization.
- Rights match the app: any member of the organization can make changes through their agent.
- Text written by AI models or third-party sites reaches your agent marked as data, not as instructions to follow.
- Each user can make up to 120 calls per minute.
To disconnect an agent, open your account menu, choose AI agents (MCP) and click Revoke. Access stops immediately.
Troubleshooting
| Message | What to do |
|---|---|
| A paid Hawkscan plan is required. | Choose a plan in Billing, then ask your agent again. |
| The subscription of this account ended. | Renew your subscription in Billing. |
| The last payment for this account failed. | Update your payment method in Billing. |
| This account is over the limits of its plan. | Upgrade or reduce your usage in Manage plan. |
| Project “…” was not found. | Ask your agent to list your projects, then use the slug it returns. |
| Too many calls to Hawkscan. Wait a minute before trying again. | Each user can make up to 120 calls per minute. Ask again a minute later. |
| Hawkscan could not complete this request. Try again in a moment. | Ask your agent again in a moment. |
| This account has no Hawkscan organization. | Sign in to Hawkscan in your browser, then start the connection again from your agent. |
| Your agent says it is not authorized | Its access was revoked or has expired. Start the connection again from your agent. |
| This connection request is no longer valid | Start the connection again from your agent. |
| Your agent asks for an API key or a client ID | Choose OAuth and leave these fields empty. |
| Your agent cannot register with the server | It needs OAuth dynamic client registration. If it does not support it, use the mcp-remote bridge. |