The Oncrawl MCP Server connects Oncrawl to AI tools that support the Model Context Protocol (MCP).
It allows you to access your Oncrawl data and run supported actions directly from your AI Assistant.
What is MCP?
The Model Context Protocol (MCP) lets AI tools connect to external data sources and services.
With MCP, your AI Assistant can interact with Oncrawl without manual exports or switching tools.
What is the Oncrawl MCP Server?
The Oncrawl MCP Server is Oncrawl’s MCP endpoint.
It exposes Oncrawl data and features as tools that AI clients can use.
With it, you can:
access workspaces, projects, and crawls
query crawl, crawl-over-crawl, and log data
analyze datasets (aggregations)
retrieve page-level details
run operations like launching crawls or managing projects
The server uses your Oncrawl account and respects your permissions.
Endpoint URL
Why use it?
Use the MCP Server to work faster with Oncrawl data in AI tools.
analyze technical SEO data more easily
speed up investigations and reporting
access insights without navigating multiple reports
combine Oncrawl with other MCP-connected tools
What can you do with it?
Analyze data
run technical SEO audits
find crawl issues and regressions
analyze orphan pages and crawlability
explore log data
Run operations
manage projects and crawl configurations
launch and monitor crawls
create comparisons and exports
Available actions depend on your permissions.
Prerequisites
Oncrawl account
Access to projects and data
MCP-compatible client
Some clients may require specific plans or settings.
Authentication and permissions
The Oncrawl MCP Server supports two authentication methods:
OAuth authentication
Token-based authentication using headers
The recommended method depends on the MCP client you use.
Option 1: OAuth authentication
OAuth is recommended when your MCP client supports the full authentication flow.
The Oncrawl MCP Server can use OAuth authentication with your Oncrawl account.
During setup:
1. Your MCP client requests access.
2. You see a consent screen showing which client is requesting access.
3. You log in to your Oncrawl account.
4. You approve the requested permissions, also called scopes.
Important
Always verify the client requesting access before approving
Permissions (scopes) determine what actions can be performed
If you do not grant write permissions, actions (create, update, delete) will not be executed
If you grant full permissions, you are responsible for any actions performed
Some actions (such as deleting projects) may be irreversible.
Option 2: Token-based authentication with headers
Some MCP clients, including some Claude setups, may work better with a direct server configuration using headers.
In this case, you can authenticate the Oncrawl MCP Server with an Oncrawl API token.
This method is useful when:
the MCP client supports custom headers
OAuth is not available or not convenient in the client
you are configuring the MCP Server manually
you are setting up Oncrawl MCP in Claude or another client requiring explicit headers
Prerequisite: Oncrawl API option
To use an API token, your subscription must include the Oncrawl API option.
If the API option is not included in your subscription, you will not be able to create or use API access tokens.
Create or retrieve an API token
From your workspace settings page, scroll down to the API Access Tokens section.
Click View API Access Tokens to see the list of tokens already generated.
For each token, the list provides:
the token description
the token permissions
the date the token was last used
a Delete button to permanently delete the token
To create a new token:
Click Add API Token at the bottom of the list.
Add a clear token description.
Use a description that helps you identify the token later.
Example:
Claude MCP - SEO team
Select the required token permissions.
Create the token.
Copy the token and store it securely.
API token permissions
When creating or reviewing a token, check its permissions carefully.
Available permissions are:
Permission | What it allows |
account read | Display the user, subscription, and quotas |
account write | Modify certain user properties |
project read | List the user’s projects and crawls |
project write | Create projects, start crawls, and remove crawls |
For most MCP analysis use cases, start with the minimum required permissions.
If the MCP client only needs to query Oncrawl data, use read permissions whenever possible.
If the MCP client needs to create projects, launch crawls, or perform write actions, the token must include the relevant write permissions.
Configure the MCP Server with headers
Use this configuration format:
{
"Oncrawl MCP": {
"url": "https://mcp.oncrawl.com/mcp",
"headers": {
"api-key": "<THE_API_TOKEN>",
"api-url": "https://app.oncrawl.com/"
}
}
}
Replace <THE_API_TOKEN> with the API token generated from your Oncrawl workspace settings.
The api-url value should remain:
https://app.oncrawl.com/
Security notes
Keep your API token private.
Do not share it in:
prompts
screenshots
Slack messages
documentation
repositories
Delete and regenerate the token if it is exposed.
The MCP Server acts with the permissions of the API token.
If the token has write permissions, the connected AI client may be able to perform write actions such as creating projects, launching crawls, or removing crawls.
Use the minimum permissions required for your workflow.
Getting started
1. Add the MCP server
Use the Oncrawl MCP endpoint:
https://mcp.oncrawl.com/mcp
Add it to any MCP-compatible client (ChatGPT, Claude, Cursor, etc.).
See setup instructions by platform:
2. Authenticate
Sign in with your Oncrawl account when prompted.
Your access and permissions will match your Oncrawl user rights.
3. Start with a simple prompt
Try one of these:
“Show my Oncrawl context”
“List my projects”
“Show my latest crawl”
4. Explore your data
You can now ask questions like:
“Count pages by status code in my latest crawl”
“Find orphan pages”
“Compare my last two crawls”
5. Run actions (if permitted)
Depending on your permissions, you can also:
create a project
launch a crawl
create a crawl configuration
schedule a crawl
Notes
The MCP Server uses standard MCP transport (Streamable HTTP)
MCP availability depends on your AI client and plan
Some platforms require developer mode or admin approval
Always connect only to trusted MCP servers
Behavior such as confirmations may vary depending on the AI client
Next steps
See the full tools reference:
Once connected, you can use the Oncrawl MCP Server as a faster interface for both analysis and operations in Oncrawl.
For advanced use cases, start by:
retrieving your user context
listing available projects or crawls
discovering fields for the relevant dataset
using OQL to refine your queries