# ako.tools

> ako.tools is Ako's home for MCP tools, on one MCP server. Its first tool, the AI visibility audit, helps businesses understand and improve how AI assistants discover, cite and recommend them.

## Set up ako.tools in four steps

1. Connect. If your MCP client supports OAuth, add https://api.ako.tools/mcp and approve in the browser; nothing else is needed. For a headless or scheduled agent, a person creates a scoped API key at https://ako.tools/agents (sign in, name the agent, choose permissions, create the key and copy it once) and the agent sends it as "Authorization: Bearer br_agent_…". If the agent has neither, use enrollment: start_user_signup (MCP at https://api.ako.tools/mcp/enroll) or POST https://api.ako.tools/v1/enrollments, show the claimUrl to the person, wait for approval with get_signup_status waitSeconds 25 (REST: GET /v1/enrollments/{id}?wait=25), and store the returned agentToken in secret settings. Every enrollment response includes nextSteps saying what to do.
2. Check it works. Call get_credit_balance (GET /v1/billing). It returns the balance and the free credit every new account gets.
3. Set up a brand. Call create_brand with the website and wait until the profile is ready. Show the person what ako.tools found (get_brand): the market (profile.country and profile.language) and what it understood the business does (profile.description and offers), and ask whether that is right. Fix it before spending credit: update_brand_market for the market (it also writes and charges for questions for the new market, so confirm that with the person first) and update_brand_profile for what the business does and its offers. The person can make the same corrections on their dashboard. Competitors are not set up front: each audit reports the other brands AI assistants offer the buyer (namedBrands). Then call generate_brand_questions, which uses the brand's market, and wait until the questions are ready.
4. Estimate, then run. For a new account or a first look, run a preview: call estimate_visibility_audit with preview true, then run_visibility_audit with preview true. It asks three questions (discovery, comparison and a customer need) of every AI assistant and writes the recommended actions, for a fraction of a full audit, and fits the free credit. When it finishes, read get_brand_visibility, show the person what it found, then say what the full audit adds (every tracked question and the cost in upgrade.fullAudit) and gently ask whether they would like to run it. If upgrade.fullAudit.canStart is false, call create_credit_top_up and share the checkout link; do not run the full audit without their yes. For a full audit, call estimate_visibility_audit (POST /v1/audits/estimate) for the cost, which is free. If canStart is false, ask the person to add credit with create_credit_top_up and share the link. Then call run_visibility_audit, poll get_visibility_audit until it finishes and read get_brand_visibility: the scores, the other brands and sites AI names, a table of every tracked question, and a verdict with recommended actions if a report has been written. get_visibility_runs has the underlying answers. Recommended actions are written only on request: pass generateReport true to run_visibility_audit, or call generate_visibility_report for a finished audit. Otherwise plan from the evidence yourself. For a one-step assessment of a website use estimate_agent_readiness_audit then run_agent_readiness_audit.

Which route fits: Claude Code, Claude, ChatGPT, Cursor or any MCP client that supports remote servers with OAuth: add https://api.ako.tools/mcp and approve in the browser (Claude Code: claude mcp add --transport http ako-tools https://api.ako.tools/mcp, then /mcp and Authenticate). An MCP client without OAuth that accepts headers: use an API key as "Authorization: Bearer br_agent_…". A chat or hosted agent with no MCP client: enrollment, where the agent starts it, shows the person the approval link and collects its own key; or the person creates an API key and gives it to the agent. Scripts, scheduled jobs, CI and automation tools: an API key over REST or MCP, stored as a secret. A person always approves an enrollment, creates an API key and pays for credit; credit belongs to the account, so every route spends the same balance.

## Preferred connection: OAuth

Add https://api.ako.tools/mcp to an OAuth-capable MCP client. The client discovers the authorization server (Clerk), opens the browser for sign-in and approval, and securely stores credentials. An OAuth connection has full access to the account. Do not call start_user_signup when the client supports OAuth. Authentication belongs to the client connection and survives individual model runs.

The client must use authorization code with S256 PKCE and resource=https://api.ako.tools/mcp, and request openid email offline_access; the connection is granted audits:read, audits:create and audits:cancel. Access tokens last one day; refresh tokens rotate on each use. Reconnect through the client if renewal fails; no demo is required.

The same access token can call REST with Authorization: Bearer <access_token>. REST and MCP share owners, scopes, quotas and service operations. Add the MCP resource parameter when obtaining a token for either surface.

Manage connections and create scoped API keys for headless agents at https://ako.tools/agents. Keys are shown once, must be stored in secret settings, and work through MCP and REST. Revoking a key disables it. Disconnecting an OAuth client refuses its tokens, including renewed ones, until the person allows it again on that page. Reconnecting uses the existing account.

## Enrollment: clients without OAuth

Creating an enrollment sends no email. Share the returned claimUrl as a clickable link in the current conversation. The user opens it, signs in (with a code emailed to them, or Google), then clicks Approve agent access. If already signed in, they can approve directly. Keep pollToken private and wait for approval with get_signup_status and waitSeconds 25 (REST: GET /v1/enrollments/{id}?wait=25), which returns as soon as the user approves, instead of polling. Save enrollmentId and pollToken in persistent private storage before sharing the link; later runs can resume the same request. Do not tell the user to check email before they enter their address on that page.

Sign-in is by Clerk: the person enters their email on the claim page and types the code it sends, or continues with Google. The agent name is not in that email. Enrollment expires after one hour. If the link expired, call refresh_signup_link (REST: POST /v1/enrollments/{id}/refresh) with the same pollToken to get a new claimUrl without starting over.

Optional restriction: only the account with this email can approve the enrollment. It does not send an invitation or sign-in email. Omit unless the user has specified the approving email address.

## Start without a demo

The AI Visibility API is available to agents through MCP and REST. Booking a demo is not required. Prefer a saved OAuth connection to https://api.ako.tools/mcp. Only clients without OAuth should use enrollment at https://api.ako.tools/mcp/enroll (start_user_signup) or POST https://api.ako.tools/v1/enrollments. Retain the enrollmentId and pollToken and resume the same enrollment after approval. See https://ako.tools/developers for both quickstarts.

Use the AI Visibility API to test brand mentions, recommendations and citations across AI assistants, using the consumer app where possible and the API where not. ako.tools also offers a demo-led managed readiness service (https://ako.tools/managed); that is separate from API enrollment.

## AI Visibility API

- [Product overview](https://ako.tools/ai-visibility-api): Commercial overview, use cases and measurement approach.
- [Developer documentation](https://ako.tools/developers): MCP and REST quickstarts, lifecycle, metrics and recovery guidance.
- [OpenAPI specification](https://ako.tools/openapi.json): Machine-readable REST API definition.
- [Full agent guide](https://ako.tools/llms-full.txt): Complete integration guidance for agents.

## Connection endpoints

- Enrollment MCP: https://api.ako.tools/mcp/enroll
- Authenticated MCP: https://api.ako.tools/mcp
- REST base: https://api.ako.tools/v1
- Service metadata: https://api.ako.tools/
- Earlier host: https://api.buyeros.ai keeps serving the same API, MCP and OAuth for connections made there. New connections use https://api.ako.tools.

## Important behavior

Access requires human-approved enrollment. Audits are asynchronous and cost-controlled. Results contain aggregate visibility metrics and prompt-level evidence. ChatGPT and Gemini are measured through their consumer apps and the other engines through search-assisted APIs. Neither claims to reproduce a signed-in or personalised assistant.

## ako.tools content

- [Insights](https://ako.tools/insights): Research and guidance from Ako.
- [Agentic commerce readiness](https://ako.tools/services/agentic-commerce-readiness): Ako's readiness service.
- [Shopify agentic commerce](https://ako.tools/insights/shopify-agentic-commerce): Merchant guide to channel eligibility, product accuracy, checkout and attribution.

Credit and pricing: work is paid from prepaid credit in US dollars, with no subscription or seats, at the same price for people, REST and MCP. Only work that succeeds is charged: a failed call, a failed technical audit or an audit run that produces no result costs nothing. Technical audits are priced per page; a new account gets $5 free. Call get_credit_balance (GET /v1/billing) for the balance, the per-page technical audit price and the top-up limits, list_credit_transactions for history and create_credit_top_up (POST /v1/billing/top-ups) for a Stripe checkout link a person opens to pay. A paid operation the account cannot cover returns 402 insufficient_credits with requiredUsd and availableUsd and queues nothing; an audit that runs out of credit stops with status partial and the results so far. Audits report costUsd and estimatedCostUsd. What an audit costs depends on the engines, questions and repetitions chosen, and its estimate is returned when it is accepted; choose fewer engines to cost less. Always call the free estimate first: it is the price of model work, including the report when generateReport is true.

Technical audit capability: audit public-site technical eligibility through POST /v1/technical-audits or run_technical_audit, then poll get_technical_audit and read get_technical_results. Audits up to 50 pages by default (maximum 10,000) discovered through sitemaps and raw links. Supply website, brandId, or both; brandId links the audit to an owned brand, supplies its website, and filters list_technical_audits. Options: maxPages (maximum 500), maxRenderedPages (maximum 50), vertical. Browser sample defaults to 10 key/template pages. Results schemaVersion 2 includes explicit coverage, grouped fixes and page evidence paginated with offset/limit. Existing audit scopes apply. Technical eligibility is separate from AI visibility outcomes. Browser rendering sends public URLs to Cloudflare; optional compressed evidence is private. See https://ako.tools/developers and OpenAPI for contracts and limits.
Agent readiness audit capability: assess whether a website is agent ready in one operation with POST /v1/agent-readiness-audits or run_agent_readiness_audit (website or brandId, idempotency key), then poll get_agent_readiness_audit and read get_agent_readiness_results. It creates or reuses the brand, runs the technical audit, generates tracked questions automatically and runs the AI visibility audit. The market is the one the brand's site serves by default; country and language narrow the visibility audit to one market (the technical audit is market-independent). Results are data only, with no score. Existing audit scopes apply. See https://ako.tools/developers and OpenAPI.

Structured outputs are schema-validated with at most one output retry. A final profile failure stops the readiness audit and cancels active child work; start a new audit to rerun. Readiness costUsd reports what the account paid by stage. Model diagnostics remain private.