Protocol reference

Endpoints#

Transport#

The server speaks MCP over Streamable HTTP. Every request is a JSON-RPC 2.0 message sent with POST, and must accept both JSON and event streams:

Accept: application/json, text/event-stream
Content-Type: application/json

Tools that use your account also need:

Authorization: Bearer imv_your_api_key

List the tools#

curl -X POST https://seoaudit.imvasa.dev/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Call a tool#

curl -X POST https://seoaudit.imvasa.dev/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"find_issues","arguments":{"url":"https://example.com","severity":"fail_only"}}}'

With your key, for a tool that uses your account:

curl -X POST https://seoaudit.imvasa.dev/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer imv_your_api_key" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"account_credits","arguments":{}}}'

Results#

Tools return a text summary in content and machine-readable data in structuredContent. Account tools include fetched_at and cached. Audit results include the public report link, https://seoaudit.imvasa.dev/s/ followed by the share id.

Troubleshooting#

The server returns 406 Not Acceptable#

Your request is missing Accept: application/json, text/event-stream. Browsers ask for HTML, so opening /mcp in a browser always shows this. Real MCP clients send the right header automatically.

Every request returns 401 invalid_token#

The Authorization header does not match an active key: a typo, a revoked key, or a token that does not start with imv_. The server rejects it rather than silently falling back to the free tools. Create a new key in API Access, or remove the header to use only the free tools.

A tool says it needs an API key#

You called an account tool without a key. Add the header, or connect through https://seoaudit.imvasa.dev/mcp/account and sign in.

A tool says your balance is too low#

Your credits have run out. The free tools keep working. See Credits and pricing.

A tool says the rate limit was reached#

Accounts can run up to 30 paid lookups per hour. Wait a few minutes and try again.

An audit fails for a site#

The site may block automated visitors, require a login, or respond too slowly. The error explains which. Try a different page, or ask the site owner to allow the crawler.