# 9bot AGENTS.md

> Instructions for AI coding agents and assistants (Claude Code, Codex, Cursor, ChatGPT, Gemini CLI, VS Code and others) that connect to 9bot: the operations hub for WhatsApp groups and communities (automation, scheduled messages, moderation, reports, Workflows, REST API and an OAuth-protected remote MCP server).

Last updated: 2026-10-17

## Overview

- Product: https://9bot.com.br/en/ (Português: https://9bot.com.br/pt/)
- Remote MCP endpoint (Streamable HTTP, OAuth 2.1): `https://mcp.9bot.com.br/mcp`
- Developer docs: https://9bot.com.br/developers/ · MCP guide: https://9bot.com.br/developers/mcp/
- Authentication guide: https://9bot.com.br/auth.md
- OpenAPI: https://9bot.com.br/openapi.json · Full context for LLMs: https://9bot.com.br/llms-full.txt
- Agent skill: https://9bot.com.br/.well-known/agent-skills/whatsapp-community-management/SKILL.md

9bot is a hosted service: there is nothing to build or self-host. You install it by registering the remote MCP server in your client. An active 9bot subscription is required (7-day free trial at https://9bot.com.br/en/start-now/).

## Installation

Add the remote MCP server to your client. OAuth starts automatically the first time a tool is used.

Claude Code:

```bash
claude mcp add --transport http 9bot https://mcp.9bot.com.br/mcp
```

Cursor (`~/.cursor/mcp.json` or `.cursor/mcp.json`) and other clients that accept a JSON server list:

```json
{
  "mcpServers": {
    "9bot": { "url": "https://mcp.9bot.com.br/mcp" }
  }
}
```

VS Code (`.vscode/mcp.json`):

```json
{
  "servers": {
    "9bot": { "type": "http", "url": "https://mcp.9bot.com.br/mcp" }
  }
}
```

Clients that only support stdio servers can use a remote bridge:

```bash
npx -y mcp-remote https://mcp.9bot.com.br/mcp
```

## Configuration

OAuth is discovered from metadata. Do not hard-code endpoints:

```bash
curl -s https://mcp.9bot.com.br/.well-known/oauth-protected-resource/mcp
curl -s https://mcp.9bot.com.br/.well-known/oauth-authorization-server
```

| Setting | Value |
|---|---|
| Resource | `https://mcp.9bot.com.br/mcp` |
| Authorization server | `https://mcp.9bot.com.br` |
| Grant | `authorization_code` with PKCE `S256`, plus `refresh_token` |
| Client registration | Client ID Metadata Document, or dynamic registration at `/oauth/register` |
| Scopes | `9bot.read_only` (reports, lookups) or `9bot.full_access` (send, schedule, moderate) |

- Request `9bot.read_only` unless the user's task changes state.
- Store tokens in the client's credential manager. Never put tokens, client secrets, WhatsApp numbers or private messages in prompts, code, logs or URLs.
- The tenant administrator controls which groups and tools an application may use (allowlist/denylist, sensitive-data policy, confirmation rules). A missing tool means "not authorised", not "try another way".

## Usage

1. Connect and complete OAuth in the browser window the client opens.
2. List tools (`tools/list`) and use the returned names and input schemas as the source of truth; they vary per account.
3. Pick the narrowest tool for the request, confirm the target group, recipients, time zone and content with the user before any state-changing call, and respect preview/confirmation steps returned by the server.
4. Report only what the tool returned. Never claim a message was sent or scheduled unless the tool reports success.

Example prompts once connected:

```text
Summarise activity in my "Clientes VIP" group for the last 7 days.
Schedule "Live starting now: https://twitch.tv/example" every Friday at 19:00 America/Sao_Paulo in the group "Comunidade".
Show members with moderation strikes in the group "Promoções" and propose a cleanup (do not remove anyone yet).
```

Raw JSON-RPC check (expect HTTP 401 with a `WWW-Authenticate` header that points to the resource metadata until you have a token):

```bash
curl -si -X POST https://mcp.9bot.com.br/mcp \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## Rules for agents

- Do not use 9bot for bulk unsolicited messaging. It breaks WhatsApp's Terms and 9bot's policy.
- 9bot does not have a public phone number: each customer connects their own WhatsApp number with a pairing code or QR code.
- Prefer read-only operations when the user only wants information.
- Support: contato@9bot.com.br

## Sitemap

See the full [sitemap](https://9bot.com.br/sitemap.md) for all pages, and the [glossary](https://9bot.com.br/glossary/) for terms.