> ## Documentation Index
> Fetch the complete documentation index at: https://bisibility.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AI agents

> Connect AI agents to bisibility through MCP or the REST API.

AI agents can create projects, add keywords, run checks, and read rank history.
They use the same authenticated operations as other API clients.

## What an agent can do

* Connect and test a SERP provider.
* Add keywords to a project.
* Run a rank check and read the result.
* Read ranking history and stored traffic snapshots.
* Review, mute, or acknowledge triggered alerts.
* Export project data or prepare a migration.

## Connect through MCP

Bisibility exposes a Model Context Protocol (MCP) Streamable HTTP endpoint:

```text theme={null}
https://your-host.example/api/mcp
```

Use `https://bisibility.com/api/mcp` for the hosted production endpoint. A
self-hosted client should use its own origin.

The MCP server card lists the endpoint and available tools:

```text theme={null}
https://your-host.example/.well-known/mcp/server-card.json
```

## Authenticate

Send a project API key as a Bearer token. The key belongs in the HTTP
`Authorization` header, not in a tool argument.

```text theme={null}
Authorization: Bearer bsk_live_...
```

For REST clients, set the API root and key in the tool environment:

```bash theme={null}
export BISIBILITY_BASE_URL="https://your-host.example/api/v1"
export BISIBILITY_API_KEY=placeholder
```

See [Authentication](/docs/docs/authentication) for key creation and a test request.

## Example workflow

1. Create or select a project.
2. Add a keyword with its country and device.
3. Start a rank check.
4. Poll the check until it completes.
5. Read the keyword's ranking history.

MCP tools and REST API v1 use the same router, so both paths return the same
project data and enforce the same permissions.

## More agent tasks

* Discover keywords that a domain already ranks for and annotate tracked terms.
* Research related queries, suggestions, and keyword ideas, then hydrate their metrics.
* Query live search-performance data or start an analytics sync.
* Generate a weekly report of ranking gains, losses, and new entries.
* Inspect, enable, or disable sitemap monitoring for a project.

## Available tools and schemas

<CardGroup cols={2}>
  <Card title="MCP server card" icon="plug" href="https://bisibility.com/.well-known/mcp/server-card.json">
    The MCP endpoint and tool inventory.
  </Card>

  <Card title="OpenAPI" icon="code" href="https://bisibility.com/api/v1/openapi.json">
    The exact REST API schema.
  </Card>

  <Card title="Capabilities" icon="sparkles" href="https://bisibility.com/api/v1/capabilities">
    Features exposed by the production API.
  </Card>

  <Card title="Agent skills" icon="book-open" href="https://bisibility.com/.well-known/agent-skills/index.json">
    Task-focused instructions that agents can discover.
  </Card>
</CardGroup>

## Advanced discovery

These endpoints help agents discover authentication, schemas, and supported
features. They are optional for a basic MCP connection.

| Surface                           | URL                                               |
| --------------------------------- | ------------------------------------------------- |
| Markdown for agents               | Send `Accept: text/markdown` to public HTML pages |
| Auth guide                        | `/auth.md`                                        |
| OAuth protected resource metadata | `/.well-known/oauth-protected-resource`           |
| Agent skills index                | `/.well-known/agent-skills/index.json`            |
| MCP server card                   | `/.well-known/mcp/server-card.json`               |
| API guide for language models     | `/api/v1/llms.txt`                                |
| OpenAPI                           | `/api/v1/openapi.json`                            |
| Capabilities                      | `/api/v1/capabilities`                            |

## Optional DNS-AID records

HTTP discovery works without DNS-AID. Operators can publish DNS records when
they also want domain-level AI discovery:

```dns theme={null}
_index._agents.your-host.example. 300 IN SVCB 1 your-host.example. alpn="h2" port="443" mandatory=alpn,port key65400="/.well-known/agent-skills/index.json" key65401="/api/v1/llms.txt"
_mcp._agents.your-host.example. 300 IN SVCB 1 your-host.example. alpn="mcp,h2" port="443" mandatory=alpn,port key65400="/.well-known/mcp/server-card.json" key65401="/api/mcp"
```

DNS-AID and DNSSEC are separate operator settings. Sign the zone and publish
the matching DS record before claiming authenticated DNS discovery. Verify the
records with a validating resolver.