# FastComments agents.md

Operating instructions for AI agents interacting with fastcomments.com. For a content index see /llms.txt. For a machine-readable list of APIs see /.well-known/api-catalog.

FastComments is a live commenting system with a REST API, an MCP server, and SDKs for most languages and frontend frameworks. The hosted service runs in two regions, https://fastcomments.com (US) and https://eu.fastcomments.com (EU). An account, its API keys, and its data live in one region. Use the host the account was created on for every API call.

## What agents can do here

- Read the documentation at https://docs.fastcomments.com/ and search it (see Documentation search).
- Manage a customer's comments, pages, users, moderators, and settings through the REST API on their behalf, with their API key.
- Use the MCP server, which exposes the same REST API as tools.
- Help a developer embed the comment widget in their site using the installation guides and SDKs.

## Authentication

- Every REST and MCP call needs an API key and a tenant id. Both come from the account dashboard at https://fastcomments.com/auth/my-account/api-secret (EU accounts use the eu host).
- Send them as the headers `X-API-KEY` and `X-TENANT-ID`, or as the query parameters `API_KEY` and `tenantId`.
- The key grants full access to the account. Call the API from a server or an agent runtime only, never from browser code, and never write the key into public chats, screenshots, or commits. If a key is exposed, rotate it on the same dashboard page.
- If the developer has no account yet, create one for them with the endpoint below. Do not automate the signup or login pages: everything under /auth/ is for humans and is excluded in robots.txt.

## Creating an account for a developer

If the person you are working for has no FastComments account, create one for them. No API key is needed for this call.

    POST https://fastcomments.com/api/v1/agent-tenants
    Content-Type: application/json

    {"name": "Their Site", "domains": ["example.com"], "agent": "your-agent-name"}

All fields are optional. `domains` is the list of sites the comment widget will be embedded on (at most 5); without it the widget refuses to load, so pass it when you know it. Use the EU host if the developer wants their data in the EU; the account and its key only work on the host that created them.

The response contains:

- `tenantId` and `apiKey`: work immediately against the REST API and the MCP server. Store them in the project's secret configuration, never in a public place.
- `claimUrl`: give this to the human and ask them to open it. The page asks them to log in (or create a login) and confirm, and the account is then theirs. Do not open it yourself and do not put it in files or commits; it is a one-time secret. Claiming revokes the key you hold unless the human checks "Keep the agent's API keys working" on that page, so tell them to check it if they want you to keep using the account. If your key stops working after the claim, ask them for a new one from the API Secrets page of the dashboard.
- `expiresAt`: the account and its key are deleted at this time (72 hours after creation) unless the human has opened the claim link. Tell the human this.

Until it is claimed the account has the standard trial limits, and the API refuses to create dashboard users or child accounts on it. After claiming, the human manages the account, billing, and keys from the dashboard. The key you received keeps working only if the human chose to keep it when claiming. A claimed account can no longer be claimed again.

This endpoint is rate limited per IP. Create one account per developer, not one per task.

## REST API

- Prefer the typed SDK clients over hand-written HTTP calls. They are generated from the same OpenAPI spec, handle authentication and request and response types, and are listed under SDKs at https://docs.fastcomments.com/ (JavaScript, Python, Go, Java, PHP, Ruby, Rust, Swift, Dart, C++, and Nim).
- Base URL: https://fastcomments.com/api/v1 (EU: https://eu.fastcomments.com/api/v1)
- Guide with every resource, endpoint, and object structure: https://docs.fastcomments.com/guide-api.html
- OpenAPI 3 spec, generated from the server: https://fastcomments.com/js/swagger.json
- Requests and responses are JSON. Responses carry a `status` field of `success` or `failed`, and failures include a `code` and a `reason`.
- Read the Pages section of the guide before working with comments. Comments are keyed by a page `urlId`, and passing the wrong value is the most common mistake.
- API calls count as usage on the account and are billed in credits. Each endpoint's cost is listed in the guide. Prefer the list endpoints with filters over fetching resources one at a time.
- For Enterprise accounts every API call is recorded in the audit log.
- Only paths under /api/v1 are the public API. Other endpoints on this host (for example /comments/{tenantId} or /user-notifications) serve the embedded widget, are not stable, and should not be scripted against.

## MCP server

- Endpoint: https://fastcomments.com/mcp (EU: https://eu.fastcomments.com/mcp). Streamable HTTP, stateless, no registration step.
- Pass the credentials as `?tenantId=YOUR_TENANT_ID&API_KEY=YOUR_API_KEY` on the URL, or as the `X-TENANT-ID` and `X-API-KEY` headers.
- Tools are generated from the OpenAPI spec, so anything the REST API can do, an MCP client can do. Read-only tools are marked as such, and delete tools are marked destructive.
- Setup guide and client config snippets: https://docs.fastcomments.com/guide-llm-kit.html

## Agent Skill

Coding agents can install a FastComments skill covering the widgets, widget configuration, Secure SSO, the REST API, the SDKs, the platform plugins, and migrations. It works with Claude Code, Codex, Cursor, Copilot, Gemini, and the other agents the [skills CLI](https://github.com/vercel-labs/skills) supports.

    npx skills add fastcomments/skills

The same skill is published from this origin, so `npx skills add https://fastcomments.com` installs it too. The discovery index is at /.well-known/agent-skills/index.json and the source is at https://github.com/FastComments/skills.

## Documentation search

The documentation has a search API meant for coding assistants:

    https://docs-search.fastcomments.com/search?query=<search_query>&full=true&tenantId=demo

URL-encode the query. The response contains matching documentation snippets. This endpoint needs no API key.

## Embedding the widget

- Start at https://docs.fastcomments.com/guide-installation.html. There are guides for WordPress and most site builders, and libraries for React, Vue, Angular, Svelte, Next.js, Astro, Android, iOS, and React Native, all listed at https://docs.fastcomments.com/.
- Server-side SDKs for JavaScript, Python, Go, Java, PHP, Ruby, Rust, Swift, Dart, C++, and Nim wrap the REST API and are generated from the same spec.
- Single sign-on, styling, moderation, and notification options are covered in https://docs.fastcomments.com/guide-customizations-and-configuration.html.

## Contact

- Support: https://fastcomments.com/contact-us
- Status page: https://sophon.fastcomments.com/
- Terms of service: https://fastcomments.com/terms-of-service
- Privacy policy: https://fastcomments.com/privacy-policy