# WriteForYou MCP — connect guide

This file is the machine-readable setup guide (no JavaScript).
Human UI: https://writer.swapp1990.org/connect
Discovery: https://writer.swapp1990.org/.well-known/mcp/server.json

## Server

| Field | Value |
|-------|--------|
| URL | `https://writer.swapp1990.org/mcp/v2/` |
| Transport | Streamable HTTP (remote MCP) |
| Trailing slash | **Required** (`/mcp/v2/` not `/mcp/v2`) |
| OAuth scopes | `openid` `profile` `email` |
| Server name | `writeforyou` (recommended in client configs) |

## Auth (pick one)

### A) OAuth (preferred when the client can open a browser)

Many clients (Claude Code, Cursor, OpenCode, Grok when OAuth works) support
OAuth 2.0 + PKCE with Dynamic Client Registration. Add the URL, then complete
the browser sign-in when prompted. No static API key required.

If the client shows the server as **disabled / not connected / auth required**
after add, OAuth did not complete. Use option B.

### B) Long-lived bearer token (Codex, Grok, headless, CI)

1. Sign in at https://writer.swapp1990.org
2. Open https://writer.swapp1990.org/connect
3. Generate a token (shown once). Store it as env var `WRITEFORYOU_MCP_TOKEN`.
4. Configure the client to send `Authorization: Bearer <token>`.
5. Revoke the token on the same page if it leaks.

Do **not** paste browser localStorage tokens into chat. Do **not** use admin or
service tokens. MCP tools must run as the signed-in WriteForYou user (library,
billing, audit).

## Client recipes

### Claude Code

```bash
claude mcp add --transport http writeforyou https://writer.swapp1990.org/mcp/v2/
# all projects on this machine:
claude mcp add --scope user --transport http writeforyou https://writer.swapp1990.org/mcp/v2/
```

Then approve OAuth in the browser when prompted.

### Grok (xAI)

OAuth path (interactive):

```bash
grok mcp add --transport http writeforyou https://writer.swapp1990.org/mcp/v2/
```

Then in the Grok TUI: `/mcps` → select `writeforyou` → press `i` to authorize
→ press `r` to refresh. Tokens land in `~/.grok/mcp_credentials.json`.

If the server stays **disabled / not connected** (common when OAuth never
finishes in agent sessions), use a long-lived token instead:

```bash
# PowerShell (Windows) — set a user env var once
[Environment]::SetEnvironmentVariable("WRITEFORYOU_MCP_TOKEN", "<paste-token-here>", "User")

# restart the shell / Grok so the env var is visible, then:
grok mcp add --transport http writeforyou https://writer.swapp1990.org/mcp/v2/ --header "Authorization: Bearer ${WRITEFORYOU_MCP_TOKEN}"
grok mcp doctor writeforyou
```

`~/.grok/config.toml` should look like:

```toml
[mcp_servers.writeforyou]
url = "https://writer.swapp1990.org/mcp/v2/"
enabled = true

[mcp_servers.writeforyou.headers]
Authorization = "Bearer ${WRITEFORYOU_MCP_TOKEN}"
```

Verify: `grok mcp doctor writeforyou` reports handshake OK and tools discovered.

### Codex

```powershell
[Environment]::SetEnvironmentVariable("WRITEFORYOU_MCP_TOKEN", "<paste-token-here>", "User")
codex mcp remove writeforyou
codex mcp add writeforyou --url https://writer.swapp1990.org/mcp/v2/ --bearer-token-env-var WRITEFORYOU_MCP_TOKEN
```

### Cursor

One-click from https://writer.swapp1990.org/connect or `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "writeforyou": {
      "url": "https://writer.swapp1990.org/mcp/v2/",
      "transport": "http"
    }
  }
}
```

### OpenCode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "writeforyou": {
      "type": "remote",
      "url": "https://writer.swapp1990.org/mcp/v2/",
      "enabled": true
    }
  }
}
```

```bash
opencode mcp auth writeforyou
opencode mcp list
```

### Claude Desktop

Add to `claude_desktop_config.json` (macOS:
`~/Library/Application Support/Claude/claude_desktop_config.json`, Windows:
`%APPDATA%\Claude\claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "writeforyou": {
      "type": "http",
      "url": "https://writer.swapp1990.org/mcp/v2/"
    }
  }
}
```

Restart Claude Desktop after editing.

## Agent checklist (curl, no browser UI)

```bash
# 1. Discover server
curl -s https://writer.swapp1990.org/.well-known/mcp/server.json

# 2. Read this guide
curl -s https://writer.swapp1990.org/.well-known/mcp/connect.md
# same content also at:
curl -s https://writer.swapp1990.org/connect.md

# 3. OAuth metadata (for clients implementing OAuth)
curl -s https://writer.swapp1990.org/.well-known/oauth-protected-resource

# 4. Smoke initialize with a bearer token (expect SSE initialize result)
curl -s -X POST https://writer.swapp1990.org/mcp/v2/ \
  -H "Authorization: Bearer $WRITEFORYOU_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"smoke","version":"1.0"}}}'
```

Unauthenticated POSTs return HTTP 401 with a `WWW-Authenticate` header pointing
at protected-resource metadata — that is expected, not a server outage.

## After connect

- Always surface `story_url` / `article_url` fields from tool responses to the user.
- Prefer free probes first: `list_stories`, `get_credits`, `list_models`.
- Full tool catalog and flows: https://writer.swapp1990.org/connect