Back to Connect AI Agent

Connecting an AI Agent — Technical Guide

This page covers everything needed to connect an external AI agent (Claude Desktop, Cursor, a custom script, or any HTTP-capable tool-calling framework) to your workspace’s SEO, AEO and GEO data — protocol details, every tool, every error you might hit, and copy-paste examples.

Overview

“A Simple Tool” exposes a read-only, MCP-compatible tool endpoint at POST https://asimpletool.in/api/mcp/. It speaks JSON-RPC 2.0 and implements the two methods that matter for tool-calling — tools/list and tools/call — backed by the exact same functions the in-dashboard chat assistant uses. Nothing an agent reads through this endpoint is fabricated: every tool either returns real data pulled live from your workspace, or an honest “nothing here yet” response if that feature hasn’t run.

⚠️ Known limitation — read this first

This is not a full, spec-verified MCP server. It implements only the tool-calling surface (tools/list/tools/call) over plain JSON-RPC-over-HTTP — there is no initialize handshake, session negotiation, or resources/ prompts support. Most raw HTTP clients (curl, Python, LangChain, custom GPT Actions) don’t care and will work immediately. MCP clients that insist on the full handshake (Claude Desktop, Cursor) need a small local bridge script to translate — provided below, in the “Claude Desktop / Cursor” tab.

Quickstart

Go to Connect AI Agent in the sidebar and generate a named API key. It’s shown exactly once — copy it somewhere safe.
Test it immediately with the “Test Connection” button, or the curl example below.
Wire it into your client of choice using the examples in the tabs below.

Authentication

Every request must include Authorization: Bearer <your key>. Keys:

are generated per-tenant, not per-website — one key can read every website in your workspace
are shown in full exactly once, at creation time — only a hash is stored server-side, so support can’t retrieve a lost key for you
can be revoked instantly and permanently from the Connect AI Agent page — revoking takes effect on the very next request
have no expiry by default — revoke keys you're no longer using rather than leaving them live

Endpoint reference

Method	Params	Returns
`tools/list`	none	Array of every available tool, its name, description, and input schema.
`tools/call`	`{ name, arguments }`	`{ content: [{ type: "text", text: "<json>" }] }` — the tool’s result, JSON-encoded as a text block per the MCP tool-result shape.

Available tools

Tool	Arguments	Returns
`list_websites`	none	Lists the websites in this tenant workspace, with their IDs. Always call this first — every other tool needs a website_id.
`knowledge_base_guidance`	website_id	The website's SEO/AEO/GEO knowledge base guidance.
`site_crawl_inventory`	website_id	The website's most recent sitewide crawl inventory.
`citation_monitoring_status`	website_id	The website's AEO/GEO citation-monitoring status.
`analytics_summary`	website_id	The website's most recent GA4 and Search Console report snapshots.

Connect your client

Works anywhere you can shell out — good for a first sanity check.

Example

curl -X POST https://asimpletool.in/api/mcp/ \
  -H "Authorization: Bearer mcpk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}'

curl -X POST https://asimpletool.in/api/mcp/ \
  -H "Authorization: Bearer mcpk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "id": 2,
        "method": "tools/call",
        "params": {"name": "list_websites", "arguments": {}}
      }'

Errors & troubleshooting

Every scenario we’ve seen or anticipated, in one place:

401 Unauthorized — "Invalid or missing API key."

Either no Authorization header was sent, the key is malformed, or the key doesn't match any key on file. Double-check you're sending `Authorization: Bearer mcpk_...` (note: Bearer, not Basic or Token), and that you copied the whole key — it was only ever shown once at creation time.

401 Unauthorized, but the key used to work

The key was revoked (from Connect AI Agent → Revoke), or it's a different key than the one your client has cached. Revoking is immediate and permanent — generate a new key and update your client/config with it.

JSON-RPC error -32601 "Unknown method"

Only `tools/list` and `tools/call` are implemented — there's no `initialize`, `resources/*`, or `prompts/*` handshake (see the compatibility note below). If your MCP client insists on calling `initialize` first, use the stdio bridge script in the "Claude Desktop / Cursor" tab, which answers that handshake locally.

JSON-RPC error -32602 "Unknown tool: ..."

The `name` in a tools/call request didn't match any of the 6 tools listed below. Names are case-sensitive and must come from a `tools/list` call — don't guess or reuse names from other MCP servers.

Tool result: {"status": "error", "detail": "website_id is required"}

Every tool except list_websites requires a `website_id` integer argument. Call list_websites first and use one of the returned IDs — this is a normal, expected response, not a bug.

Tool result: {"status": "error", "detail": "No website with id=..."}

The website_id doesn't belong to this tenant (or doesn't exist). IDs aren't shared across tenants/workspaces — always resolve them via list_websites rather than hardcoding one.

A tool returns mostly empty/null fields

This is expected, not an error, for a website that hasn't run that feature yet — e.g. citation_monitoring_status will be sparse until Citation Intelligence has run at least once, analytics_summary until GA4/Search Console are connected. The tool always returns real data or an honest "nothing yet" shape — never fabricated content.

JSON-RPC error -32000 "Tool call failed."

An unexpected server-side error while running the tool. This is logged on our end with the tenant and tool name. Retry once; if it persists, contact support with the tool name and the approximate time of the call.

Request hangs or times out

Set a client-side timeout (20–30s is plenty — every tool here reads already-computed data, it never triggers a live crawl or LLM call). If it's still hanging past that, treat it as a transient server issue and retry.

Can a key write, publish, or change anything?

No. Every tool is read-only. There is no publish/edit/delete tool exposed over this endpoint — an agent holding your key can only read the same SEO/AEO/GEO data you'd see in the dashboard.

Is there a rate limit or usage quota on MCP calls?

Not currently metered the way the in-dashboard chat widget is (that consumes a per-billing-cycle chat_messages quota). MCP tool calls aren't quota-limited today — treat the key with the same care as a production credential regardless.

Can I scope a key to just one website?

Not yet — a key can read every website in the tenant workspace it was created in via list_websites + website_id. If you only want an agent to see one site, that's a trust boundary you enforce in your own client/prompt, not something the key itself restricts.

Security notes

Treat a key exactly like a password — anyone holding it can read every website in your workspace via any MCP-capable agent.
Revoke a key the moment a device, teammate, or integration no longer needs it — there’s no cost to generating a fresh one.
All tools are strictly read-only — there is nothing an agent can publish, edit, or delete through this endpoint.