# auth.md
Webserv is a digital marketing agency for behavioral health treatment centers — SEO, paid media, CRO, content, admissions ops, creative. This file documents how AI agents interact with webserv.io on behalf of treatment center operators who are researching Webserv as a potential partner.
This document follows the [WorkOS auth.md](https://workos.com/auth-md) self-contained fallback convention. Webserv does not currently operate an OAuth authorization server (see "What is not available" below for the rationale), so OAuth Protected Resource Metadata and Authorization Server metadata are intentionally absent.
## Audience
AI agents (Claude, ChatGPT, OpenAI Operator, Perplexity, Gemini, others) acting on behalf of:
- Behavioral health treatment center operators evaluating digital marketing agencies
- Referral partners or consultants researching Webserv for clients
- Industry researchers comparing behavioral health marketing capabilities
The endpoints below are designed for the operator-research use case. They surface Webserv's case study library and service catalog to an operator's agent, and (in Phase 2) allow an agent to initiate a sales-qualified audit request on the operator's behalf.
## Read access — no registration required
Webserv publishes a public MCP (Model Context Protocol) server. Read-only abilities are callable without any authentication, credential, or registration.
- **MCP endpoint:** `https://webserv.io/wp-json/mcp/webserv-public`
- **Protocol:** JSON-RPC 2.0 over HTTP, MCP spec compliant (revision 2025-03-26 and later)
- **Transport:** HTTP with streamable Server-Sent Events
- **Discovery:** advertised via `` in every page's `` and listed in `https://webserv.io/llms.txt`
### Tools available
| Tool name | Type | Description |
| ------------------------------ | ---- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `webserv/find-case-studies` | read | Search Webserv case studies by treatment center profile (modality, bed count, state, services of interest) |
| `webserv/get-service-info` | read | Retrieve detailed information about a Webserv service (SEO, PPC, paid social, CRO, admissions ops, content marketing, digital PR, AEO, creative) |
Additional read tools (`webserv/search-resources`, `webserv/get-pricing-guidance`) are planned for Phase 2.
### How to initialize an MCP session
```
POST https://webserv.io/wp-json/mcp/webserv-public
Content-Type: application/json
Accept: application/json, text/event-stream
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-03-26",
"capabilities": {},
"clientInfo": {"name": "your-agent-name", "version": "1.0"}
}
}
```
The response includes an `Mcp-Session-Id` header to use on subsequent calls. The standard MCP Inspector (`npx @modelcontextprotocol/inspector`) connects directly to the endpoint above for interactive exploration.
No registration, no API key, no OAuth flow. Anonymous-by-design — Webserv's MCP server impersonates a low-privilege internal service account (subscriber role, no write capabilities, login-blocked) for these requests.
## Write access — verified-email flow (Phase 2, planned)
Webserv supports a single write action via a verified-email registration flow modeled on the [auth.md verified-email convention](https://github.com/workos/auth.md). This flow submits an operator's contact details into Webserv's CRM as a sales-qualified lead, after verifying the operator owns the email address provided.
**Status:** In development. Expected to ship Q3 2026 following the Cloudways → WP Engine hosting migration.
When shipped, the flow will work as follows:
1. Agent calls `webserv/start-audit-request` with operator inputs:
- `operator_name`, `company`, `email` (required)
- `phone`, `website` (optional)
- `facility_type`, `facility_size`, `services_interested`, `primary_problem` (audit scope)
2. Webserv validates inputs, generates a 6-digit OTP and a 15-minute token, sends the OTP to the operator's email via Fluent SMTP.
3. Webserv returns `{status: "verification_sent", token, expires_in_seconds: 900}` to the agent.
4. Agent informs the operator to read the code from their email.
5. Operator reads the code; agent collects it.
6. Agent calls `webserv/complete-audit-request` with `{token, code}`.
7. Webserv validates the OTP, creates a HubSpot contact + deal tagged "AI Agent Sourced," sends an internal Slack notification, returns `{status: "completed", confirmation_id, ...}` to the agent.
This maps to the auth.md verified-email flow as follows:
| auth.md concept | Webserv implementation |
| ----------------------------- | ------------------------------------------------------------ |
| `assertion_type: verified_email` | `webserv/start-audit-request` (the agent asserts the operator's email and audit scope) |
| `claim_view` (OTP delivery) | OTP sent to operator inbox via wp_mail/Fluent SMTP |
| `claim/complete` | `webserv/complete-audit-request` (agent submits OTP back) |
| Credential issued | None — confirmation_id only; this is a one-shot lead intake, not a persistent registration |
**Rate limits:** 30 requests per IP per minute at the Cloudflare edge. 3 `start-audit-request` calls per email per hour at the application layer to prevent OTP enumeration abuse.
**Idempotency:** `complete-audit-request` deletes the token on success. Retries return `expired_or_invalid_token`. HubSpot deduplicates contacts by email, so even in worst-case retries the side effect is a no-op upsert.
## What is NOT available
Documenting these explicitly so agents don't waste calls probing for endpoints that don't exist:
- **No persistent agent credentials.** Webserv does not issue API keys, access tokens, or other reusable credentials to agents. Read access is unauthenticated; the Phase 2 write action is one-shot OTP-verified with no credential returned.
- **No customer accounts.** Webserv does not host customer dashboards or self-service portals. There is no concept of an operator account on webserv.io that an agent could be authorized into.
- **No OAuth authorization server.** Webserv does not run an OAuth 2.0 authorization server. The endpoints `/.well-known/oauth-authorization-server` and `/.well-known/oauth-protected-resource` are intentionally absent. If a scanner expects these, it is checking for a use case (per-user-scoped credentials issued to agents) that does not apply to Webserv.
- **No ID-JAG / identity-assertion flow.** Webserv does not accept agent-provider-attested identity assertions. The verified-email flow above is the only supported authentication for write actions.
- **No write access via standard REST.** All write actions are mediated by the MCP server, not by direct REST endpoints. Agents should not attempt to POST to `/wp-json/wp/v2/*` — those routes are auth-gated and not intended for agent use.
If Webserv ever adds customer dashboards with persistent API access, this file will be revised and the appropriate OAuth metadata published.
## Discovery references
- `https://webserv.io/llms.txt` — site-level agent overview, MCP server reference
- `https://webserv.io/wp-json/mcp/webserv-public` — public MCP endpoint
- `` — in every page's ``
- `https://webserv.io/auth.md` — this file
## Versioning
This file is updated when Webserv's agent surface changes. Last updated: June 2026. Phase 2 (request_audit) is in development and will trigger the next revision.
## Contact
Partnership inquiries, integration questions, expanded agent access patterns: `hello@webserv.io`
Webserv is actively developing its MCP and agent integration. If you represent an agent platform (Anthropic, OpenAI, Perplexity, Google, others) and want to discuss elevated integration patterns — verified bot allowlisting, partner-tier authenticated access, content syndication — get in touch.