Developers
Use Novagentum from an AI agent
Connect Claude, Claude Code or ChatGPT to Novagentum. Then ask in plain words: crawl my site, tell me what is wrong, and fix it. This page shows each step, gives you prompts to paste, and shows the same workflow as REST API calls for scripts and CI.
What Novagentum does, and what it doesn't
Novagentum reads your website from the outside, like a search engine or an AI assistant does. Three things are worth knowing before you start.
- A crawl collects evidence. A crawl visits up to the number of pages you choose and checks each one for problems in AI visibility, SEO and security. The result is a list of findings: each one is a problem, the page it is on, the evidence and the fix.
- Visibility is a separate, larger report. A Visibility report asks ChatGPT, Claude, Perplexity and Gemini the questions your buyers ask, and grades how each one presents your business. It builds on a finished crawl, takes one to two minutes, and costs more than a crawl. Your agent only runs it when you ask for it.
- Making fixes needs your own access. Novagentum never changes your website. Your AI agent makes the changes, and only where you have given it access: your code repository in Claude Code, or your CMS (content management system) if you edit pages by hand. Novagentum gives the agent a fix brief, a list of changes written for a coding agent.
Connect your AI tool
Novagentum works with AI tools through MCP (Model Context Protocol), an open standard that lets an AI tool call outside services. Every tool connects to the same server URL:
https://www.novagentum.ai/api/mcpClaude (web and desktop)
- Open Claude and go to Settings, then Connectors.
- Choose Add custom connector.
- Name it Novagentum and paste the server URL above. Choose Add.
- Choose Connect. Claude opens the Novagentum sign-in page (see Sign in and set a limit).
- In a chat, turn the Novagentum connector on from the tools menu if it is not on already.
On Team and Enterprise plans, an owner may need to add the connector for the organization first. Menu names can change; Claude's help center has the current steps.
Claude Code
Run this in your terminal:
claude mcp add --transport http novagentum https://www.novagentum.ai/api/mcpThen start Claude Code, run /mcp, choose novagentum and follow the sign-in steps in your browser. Add --scope user to use Novagentum in all your projects, not only the current one. If a flag has changed, check claude mcp add --help.
Claude Code is the best fit for the full workflow: it can read the findings and edit the code of your site in the same session.
ChatGPT
- In ChatGPT, open Settings, then Apps (called Connectors on some plans), then Advanced settings, and turn on Developer mode.
- Back in Apps, choose Create. Name it Novagentum, paste the server URL above and choose OAuth for authentication.
- Sign in when ChatGPT opens the Novagentum sign-in page.
- In a chat, add Novagentum from the tools menu, then ask your question.
Developer mode and custom apps are available on some ChatGPT plans only, and on business plans an admin may have to allow them. The menu names change often; OpenAI's help center has the current steps.
Cursor and VS Code
Add the server URL as a remote (HTTP) MCP server in the editor's MCP settings. The editor opens the same sign-in page.
Sign in and set a limit
When you connect, Novagentum shows a sign-in page. Sign in with your Novagentum account, then choose two things:
- Charge runs to: your personal account or a workspace you belong to. Only workspaces you are allowed to spend from work.
- Monthly spending limit: $5, $10, $25, $50 or $100 a month for this connection (default $10). Before a paid tool runs, its highest possible price is set aside against the limit. If that would pass the limit, the tool does not run. The limit resets on the 1st of each month (UTC).
Choose Approve. The connection can run paid scrapes, maps and crawls within the limit and read their results. It cannot change your account, billing or workspaces. To change the balance or the limit, connect the tool again: the new choice replaces the old one. To remove it, open Developer, find Connected AI tools and choose Disconnect.
The workflow: crawl, fix, re-crawl
You talk to your agent in plain words. The agent picks the Novagentum tools. Here is what happens at each step, and which tool it uses.
- Crawl the site. The agent calls
novagentum_crawlwith your site and a page limit (default 10, up to 100). The crawl starts and runs in the background, usually for one to a few minutes. The price grows with the page limit, so start small. - Check the status. The agent calls
novagentum_check_crawl_statusabout every 15 seconds until the status iscompleted. Checking is free. - Read the findings. The agent calls
novagentum_crawl_findings. Findings come sorted by impact, highest first. Each has a severity (high, medium or low), a category, the affected page, the evidence, why it matters and the fix. Reading findings is free. - Get a fix brief. The agent calls
novagentum_fix_brief. The brief is Markdown: each problem, the page, the expected change and an acceptance check (a test that shows the fix worked). It is free. - Make the fixes. The agent edits your site with the access you gave it, for example your repository in Claude Code. It should change only what the brief lists, keep your facts, and run your tests. Review the changes and deploy them as you normally do.
- Re-crawl to confirm. After you deploy, ask for a new crawl of the same site with the same page limit. Its findings show what changed since the last crawl: each finding is marked new, worse, better or still open, and fixed findings are listed. A re-crawl is charged like any crawl.
To find an earlier crawl, the agent can call novagentum_list_crawls. To stop a crawl that is still running, it calls novagentum_cancel_crawl: pages already checked are charged, and the rest of the reserved amount goes back to your balance. novagentum_usage shows your balance and how much of the connection's limit is used.
For a Visibility report, the agent calls novagentum_visibility_report with the id of a finished crawl and your company name, industry, location and services. It reads a saved report with novagentum_get_visibility_report. Visibility is not available on every account yet. When it is not, the tool says so and nothing is charged.
Prompts you can paste
Replace example.com with your own site.
Crawl example.com with Novagentum, 20 pages, and list the top problems with fixes.
Check my Novagentum credits and how much of this connection's limit is left.
Show only the high-severity security findings from my last Novagentum crawl of example.com.
Get the Novagentum fix brief for my last crawl of example.com. Fix the high and medium items in this repository, run the tests, and summarize what you changed and what you could not fix.
I deployed the fixes. Crawl example.com again with Novagentum, 20 pages, and tell me which findings are fixed and which are still open.
Run a Novagentum Visibility report on my last crawl of example.com. We are Example Co, a B2B SaaS company in Germany selling invoicing software. Tell me the price before you start.
Costs, limits and retries
- Paid tools:
novagentum_crawl,novagentum_scrape,novagentum_batch_scrape,novagentum_mapandnovagentum_visibility_report. Everything else is free. - Prices are the same as in the dashboard and the API. A crawl reserves its maximum price and charges only for the pages it checked. Pages that fail are not charged.
- When a call would pass the connection's monthly limit, the tool returns
MCP_SPEND_LIMITand nothing runs. To raise the limit, connect the tool again with a higher one. - Each crawl tool call starts a new crawl. If a chat is cut off after a crawl started, ask the agent to list your crawls before it starts another one, so you do not pay twice.
- Scheduled re-crawls (weekly or monthly) cannot be started from an AI tool. Start them on a finished crawl's page in the dashboard, or with the API. An AI tool can list and stop them.
Automate it with the REST API
For scripts, servers and CI (continuous integration), call the REST API with an API key. The steps are the same as above. The full reference is on MCP and API and in openapi.json.
1. Create an API key
In Developer, under API keys, create a key. Choose what it spends from: your personal account or one workspace. You can also give it a monthly spending limit. The full key starts with ng_ and is shown once. Store it as a secret, for example in $NOVAGENTUM_TOKEN, and send it in the Authorization header.
Authorization: Bearer $NOVAGENTUM_TOKENA workspace key always spends from its own workspace, so you do not need to send workspaceId. Sending another workspace returns 403 API_KEY_WORKSPACE.
2. Get a quote (free)
QUOTE=$(curl -s "https://www.novagentum.ai/api/v1/crawl/quote?limit=20&output=audit" \
-H "Authorization: Bearer $NOVAGENTUM_TOKEN")
MAXIMUM=$(echo "$QUOTE" | jq .data.maximumCents)
VERSION=$(echo "$QUOTE" | jq -r .data.priceVersion)data.maximumCents is the most the crawl can cost and data.unit says what it counts: credits or cents. Keep data.priceVersion too.
3. Start the crawl
REQUEST_ID=$(uuidgen | tr A-Z a-z)
curl -s https://www.novagentum.ai/api/v1/crawl \
-H "Authorization: Bearer $NOVAGENTUM_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com","limit":20,
"requestId":"'$REQUEST_ID'",
"quotedMaximumCents":'$MAXIMUM',"quotedPriceVersion":"'$VERSION'"}'The response has the crawl id, its status (normally queued) and your requestId. Sending the quote back is optional. If you send it and the price has changed, the crawl does not start and you get 409 QUOTE_CHANGED.
Retries never pay twice
Network errors happen. Two features make a retry safe:
requestIdis a UUID you choose for one crawl. Novagentum saves it with the crawl and with the balance reservation. A second request with the samerequestIddoes not reserve or charge again: it returns the crawl that is already queued, running or finished. If you leave it out, Novagentum makes a new one for you and returns it, but then a retry is a new crawl. So create it yourself and keep it until you have the crawl id.Idempotency-Keyis an optional header with any unique text up to 255 characters. The same key with the same body within 24 hours returns the first response again, with the headerIdempotent-Replayed: true, without new work or charge. While the first request is still running, a retry gets 409IDEMPOTENCY_IN_PROGRESS; wait and try again. The same key with a different body gets 409IDEMPOTENCY_CONFLICT. Without arequestIdin the body, the key also sets one, so both protections apply.
4. Poll until it finishes (free)
curl -s https://www.novagentum.ai/api/v1/crawl/$CRAWL_ID \
-H "Authorization: Bearer $NOVAGENTUM_TOKEN"Repeat until status is completed, failed or cancelled. Start after about 2 seconds and slow down to every 5 to 10 seconds. Reads count against your plan's read limit; over it you get 429 with a Retry-After header.
5. Read the findings (free)
curl -s "https://www.novagentum.ai/api/v1/crawl/$CRAWL_ID/findings?severity=high,medium" \
-H "Authorization: Bearer $NOVAGENTUM_TOKEN"data.findings is sorted by impact (0 to 100). Each finding has category, severity, pageUrl (null for the whole site), headline, evidence, whyItMatters and fix. data.counts counts findings by severity. If data.locked is true, fix is null until the crawl's charge has settled; read again shortly. Filter with severity and category (technical, structured_data, content, ai_visibility, competitors, security).
6. Get the fix brief (free)
curl -s "https://www.novagentum.ai/api/v1/crawl/$CRAWL_ID/fix-brief?format=markdown" \
-H "Authorization: Bearer $NOVAGENTUM_TOKEN" > fix-brief.mdGive fix-brief.md to your coding agent, for example in a CI job that opens a pull request for review. Without format=markdown, the answer is JSON with the Markdown in data.markdown. Read the brief only after the crawl is completed.
7. Re-crawl and compare
After the fixes are live, start a new crawl of the same site with a new requestId. The new crawl's findings compare it with the last crawl of that site. data.changes counts new, fixed, worse, better and still-open findings and lists up to 50 fixed ones in fixedFindings. Each finding has a change field: new, worse, better or still_open. To re-crawl on a timer instead, use scheduled re-crawls.
Errors and revoking access
Errors are JSON: { "success": false, "error": "…", "code": "…" }. A request refused with a 4xx status did not run and was not charged. These are the codes a crawl script should handle:
| Status | Code | What to do |
|---|---|---|
| 401 | AUTH_REQUIRED, AUTH_INVALID | No key was sent, or the key is invalid or revoked. Check the secret; do not retry. |
| 402 | INSUFFICIENT_BALANCE | The balance cannot cover the crawl's maximum price. Nothing ran. Add credits, then retry. |
| 402 | SPEND_LIMIT | The key's monthly limit cannot cover the maximum price. Nothing ran. Raise the limit or wait for resetsAt. |
| 403 | API_KEY_WORKSPACE, WORKSPACE_SPEND_NOT_ALLOWED | The key cannot spend from that balance, or a workspace admin has not allowed you to spend. |
| 409 | QUOTE_CHANGED | The price changed since your quote. Get a new quote and show it before you start again. |
| 409 | DUPLICATE_REQUEST | A request with this requestId is still starting. Retry with the same requestId to get the crawl. |
| 409 | IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS | The Idempotency-Key was used for a different body, or the first request is still running (retry after Retry-After). |
| 429 | CRAWL_CONCURRENCY_LIMIT, RATE_LIMITED | Too many crawls in progress for your plan, or too many requests. Wait for Retry-After. |
| 503 | UNAVAILABLE and others | A temporary problem. Retry with the same requestId or Idempotency-Key, so you never pay twice. |
To revoke an API key, open Developer and choose Revoke next to the key. It stops working at once and then gets 401 AUTH_INVALID. Leaving a workspace revokes your keys for it. Signing out or changing your password does not revoke API keys, so revoke them after a leak. To remove an AI tool, choose Disconnect under Connected AI tools.