# NewsletterFIT agent authentication

Short guide for agents connecting to the NewsletterFIT MCP server and REST API.

## Endpoints

| Purpose | URL | Method |
| --- | --- | --- |
| MCP (streamable HTTP) | https://newsletterfit.com/mcp | POST |
| MCP docs (setup, tools, errors) | https://newsletterfit.com/docs/mcp.md | GET |
| MCP tool schemas | https://newsletterfit.com/api/v1/mcp-tools.json | GET |
| OpenAPI 3.1 (REST) | https://newsletterfit.com/api/v1/openapi.yaml | GET |
| Scalar docs | https://newsletterfit.com/docs/api | GET |
| REST reference (Markdown) | https://newsletterfit.com/docs/api.md | GET |
| REST base | https://newsletterfit.com/api/v1 | — |
| Agent identity (tool inventory) | https://newsletterfit.com/.well-known/agent.json | GET |
| MCP server card | https://newsletterfit.com/.well-known/mcp/server-card.json | GET |

Transport: **streamable HTTP**, JSON-RPC 2.0. Clients must send `Accept: application/json, text/event-stream`.

## Credentials

- **OAuth 2.1** for connectors that take only a URL (Claude.ai, ChatGPT): the 401 from `/mcp` names the protected resource metadata (RFC 9728), which names the authorization server `https://newsletterfit.com/api/auth` (metadata at `/.well-known/oauth-authorization-server`). Clients register dynamically (RFC 7591), then use authorization code + PKCE (S256) with `resource=https://newsletterfit.com/mcp`. Scope `mcp:read` allows every read tool on the user's plan, never exports. The account must have a confirmed email.

- **Bearer API key** for Claude Desktop / Claude Code / curl: `Authorization: Bearer nf_live_<keyId>_<secret>` (or `nf_test_…`).
- Mint keys in the NewsletterFIT app under Billing / API keys after a plan with API access (Pro, Intelligence, or Enterprise).
- Default key scopes: `search:read`, `publications:read`, `entities:read`.
- `mcp:use` satisfies **every** MCP tool (purpose-built MCP keys). Export still needs plan entitlement `exports` (Enterprise).
- Without `mcp:use`, each tool requires its declared scope. `list-watchlist` accepts `publications:read` (or `watchlist:read`); `list-alerts` accepts `search:read` (or `alerts:read`).
- MCP responses use typed ids (`nl_`, `is_`, `sp_`, `tp_`, `en_`). REST path params and REST JSON `id` fields stay numeric.

## Limits

MCP tool calls share the same monthly meters as REST (`apiSearch`, `apiProfileView`, `export`). Failed tool calls do not increment usage. Rate limits are shared across MCP and REST per key.

Unauthenticated MCP calls return **401** with `WWW-Authenticate: Bearer realm="mcp"` and a `resource_metadata` URL.

## Not yet supported

- Agent-verified ID-JAG registration and user-claimed OTP ceremonies.
- Alert/watchlist **mutations** over MCP (list tools exist; create/update/delete remain in the app).

## Related

- Agent identity: https://newsletterfit.com/.well-known/agent.json
- Product map: https://newsletterfit.com/llms.txt
- Protected resource metadata: https://newsletterfit.com/.well-known/oauth-protected-resource/mcp