# auth.md

Mountain Web Studio — agent authentication and registration policy.

## Overview

Every public Mountain Web Studio API is open. No credentials, tokens, API keys, or registration are
required, and there is no paid tier gating access.

- `GET  https://mountain-web-studio.com/api/services` — service lines, price bands, turnaround times
- `GET  https://mountain-web-studio.com/api/projects` — portfolio list
- `GET  https://mountain-web-studio.com/api/projects/{slug}` — one full case study
- `POST https://mountain-web-studio.com/api/contact` — submit a project inquiry (sandbox supported)
- `POST https://mountain-web-studio.com/api/mcp` — MCP over Streamable HTTP

## agent_auth

```json
{
  "skill": "https://mountain-web-studio.com/.well-known/agent-skills/index.json",
  "instructions": "https://mountain-web-studio.com/agent-instructions.md",
  "openapi": "https://mountain-web-studio.com/openapi.json",
  "mcp": "https://mountain-web-studio.com/api/mcp",
  "register_uri": null,
  "sandbox": {
    "type": "inline",
    "description": "POST /api/contact with \"sandbox\": true validates the payload and returns a simulated success without sending email.",
    "endpoint": "https://mountain-web-studio.com/api/contact"
  },
  "methods": [
    {
      "type": "none",
      "description": "All APIs are publicly accessible. No registration or credentials required."
    }
  ]
}
```

## Sandbox / test environment

`POST /api/contact` accepts a `sandbox` boolean. When true the request is validated exactly as a
live one, and a simulated success is returned — no email is delivered and nothing is recorded.

```bash
curl -X POST https://mountain-web-studio.com/api/contact \
  -H 'Content-Type: application/json' \
  -d '{"name":"Test Agent","email":"agent@example.com","message":"Shape check.","sandbox":true}'
# → {"ok":true,"sandbox":true,"message":"Sandbox mode — …"}
```

The read endpoints (`/api/services`, `/api/projects`) are side-effect free, so they need no sandbox.

## OAuth Metadata

For agents that require formal OAuth discovery documents (none of the endpoints above need them):

- Authorization server: `https://mountain-web-studio.com/.well-known/oauth-authorization-server`
- Protected resource: `https://mountain-web-studio.com/.well-known/oauth-protected-resource`

## API Reference

The authoritative, machine-readable description is the OpenAPI 3.1 document:

`https://mountain-web-studio.com/openapi.json` (JSON) ·
`https://mountain-web-studio.com/api/openapi.yaml` (YAML)

Human-readable docs: `https://mountain-web-studio.com/docs`

### GET /api/services

Returns service lines with starting prices plus engagement tiers with ranges and turnaround times.
Optional `country` query parameter (ISO 3166-1 alpha-2) selects market-adjusted pricing.

Response: `200 OK`, `application/json`.

### GET /api/projects

Returns a JSON array of portfolio projects. Optional `limit` (1–100) and `type` (substring match)
query parameters.

Response: `200 OK`, `application/json`.

### GET /api/projects/{slug}

Returns one full case study. `404` with a JSON error body if the slug is unknown.

### POST /api/contact

Submits a project inquiry.

```
POST https://mountain-web-studio.com/api/contact
Content-Type: application/json

{
  "name": "string (required)",
  "email": "string (required, valid email)",
  "message": "string (required)",
  "sandbox": "boolean (optional, default false)"
}
```

Response: `200 OK` on success, `400` for malformed JSON, `422` for validation failure, `500` if
delivery fails.

## Errors

Every non-2xx response is JSON, never HTML:

```json
{
  "error": {
    "code": "validation_failed",
    "message": "`email` must be a valid email address.",
    "hint": "Supply the address the studio should reply to.",
    "field": "email",
    "docs": "https://mountain-web-studio.com/docs#submitInquiry"
  }
}
```

Codes: `invalid_json`, `validation_failed`, `not_found`, `method_not_allowed`,
`unsupported_media_type`, `delivery_failed`, `internal_error`.

## MCP Server

Streamable HTTP endpoint: `https://mountain-web-studio.com/api/mcp`

- Manifest: `https://mountain-web-studio.com/.well-known/mcp.json`
- Server card: `https://mountain-web-studio.com/.well-known/mcp/server-card.json`
- Tools: `list_projects`, `get_project`, `list_services`, `submit_inquiry`
- Authentication: none

```json
{
  "mcpServers": {
    "mountain-web-studio": {
      "type": "http",
      "url": "https://mountain-web-studio.com/api/mcp"
    }
  }
}
```