MCP Server - Phosra Developer Docs

The @phosra/mcp package turns the Phosra API into Model Context Protocol tools. Point Claude Desktop, Cursor, or any MCP-compatible client at it and your agent can read a family’s Brief, audit enforcement decisions, and apply age-appropriate policy — through natural conversation, over a signed, per-family token.

Everything on this page is verified against the published package @phosra/mcp@0.4.0 (npm), run end-to-end against the hosted sandbox https://phosra-api-sandbox-production.up.railway.app/api/v1. The binary is phosra-mcp; a live tools/list returns 79 tools. Every JSON response below is real, unedited server output.

How it works

┌─────────────┐   MCP (stdio)   ┌──────────────┐   HTTPS + Bearer phomcp_…   ┌────────────┐
│  Your agent │ ───────────────▶│  phosra-mcp  │ ──────────────────────────▶ │ Phosra API │
│ (Claude/…)  │◀─────────────── │  (local)     │◀────────────────────────── │            │
└─────────────┘   tool results  └──────────────┘        JSON responses        └────────────┘

The server runs locally, as a subprocess of your MCP client, and speaks JSON-RPC over stdio — no inbound ports, no daemon. Each of its 79 tools maps 1:1 to a Phosra REST endpoint. Every request carries your MCP token as Authorization: Bearer phomcp_…; the API resolves it to your user and family, so the agent only ever sees your own data.

Step 1 — Get an MCP token

MCP tokens are scoped to a single family and start with the prefix phomcp_. They are hashed at rest (SHA-256) and shown in plaintext exactly once, at creation.

Dashboard (recommended)
API

Open Dashboard → Keys & Auth → MCP Tokens (“Connect Phosra to your AI agent”).
Enter a label (e.g. Claude Desktop) and click Generate.
Copy the token immediately — it is displayed once and never shown again.

Revoke a token any time from the same page; the agent loses access on the next call.

Mint a token programmatically against the control plane (base URL https://prodapi.phosra.com/api/v1, the same host as all other management operations). This endpoint requires your WorkOS session bearer — see Create MCP token.

curl -X POST https://prodapi.phosra.com/api/v1/mcp-tokens \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $WORKOS_SESSION_TOKEN" \
  -d '{"label":"Claude Desktop"}'

{
  "token": {
    "id": "b1e0c9a2-7f3d-4a11-9c2e-1d4f6a8b0c33",
    "label": "Claude Desktop",
    "token_prefix": "phomcp_MFRGGZDF",
    "created_at": "2026-07-06T03:29:47Z"
  },
  "plain": "phomcp_MFRGGZDFMZTWQ2LKNNWG23TPOBYGC4TF"
}

The plain field is the full token — store it in a secret manager now. Only token_prefix (first 8 chars) is retained server-side. See also List MCP tokens and Revoke MCP token.

Treat an MCP token like a password. It grants an agent full read/write access to your family’s policies. If one leaks, revoke it — revocation is instant and irreversible.

Step 2 — Install

Run directly with npx (no install), pointing at the hosted sandbox while you build:

npx @phosra/mcp \
  --api-key=phomcp_YOUR_TOKEN \
  --api-url=https://phosra-api-sandbox-production.up.railway.app/api/v1

Or install globally:

npm install -g @phosra/mcp
phosra-mcp --api-key=phomcp_YOUR_TOKEN

The --api-key and --api-url flags also read from PHOSRA_API_KEY and PHOSRA_API_URL. When --api-url is omitted the server targets production (https://prodapi.phosra.com/api/v1).

Sandbox first. The hosted sandbox is seeded, resettable, and safe to write to — every example on this page runs against it. Switch to production only once your flow works end-to-end.

Step 3 — Configure your client

Claude Desktop
Cursor
Any MCP client

Add to claude_desktop_config.json, then fully quit and reopen Claude Desktop:

{
  "mcpServers": {
    "phosra": {
      "command": "npx",
      "args": [
        "@phosra/mcp",
        "--api-key=phomcp_YOUR_TOKEN",
        "--api-url=https://phosra-api-sandbox-production.up.railway.app/api/v1"
      ]
    }
  }
}

The config file lives at:

macOS — ~/Library/Application Support/Claude/claude_desktop_config.json
Windows — %APPDATA%\Claude\claude_desktop_config.json

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project), then reload the MCP servers list in Settings → MCP:

{
  "mcpServers": {
    "phosra": {
      "command": "npx",
      "args": [
        "@phosra/mcp",
        "--api-key=phomcp_YOUR_TOKEN",
        "--api-url=https://phosra-api-sandbox-production.up.railway.app/api/v1"
      ]
    }
  }
}

Any client that launches a stdio MCP server works. Launch:

command: npx
args:    @phosra/mcp --api-key=phomcp_YOUR_TOKEN --api-url=<base>

Prefer environment variables? Drop the flags and set PHOSRA_API_KEY / PHOSRA_API_URL in the subprocess environment instead.

Step 4 — Verify the connection

You don’t need a full client to smoke-test the server — pipe a JSON-RPC handshake over stdio. Against the hosted sandbox this returns the live tool list:

{
  echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"verify","version":"1"}}}'
  echo '{"jsonrpc":"2.0","method":"notifications/initialized"}'
  echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
  sleep 2
} | npx @phosra/mcp \
      --api-key=phomcp_YOUR_TOKEN \
      --api-url=https://phosra-api-sandbox-production.up.railway.app/api/v1 \
  | node -e 'let d="";process.stdin.on("data",c=>d+=c).on("end",()=>{for(const l of d.split("\n").filter(Boolean)){const j=JSON.parse(l);if(j.id===2)console.log("tools:",j.result.tools.length)}})'

tools: 79

On startup phosra-mcp@0.4.0 prints Registering 42 tools... to stderr. That banner string is cosmetic and undercounts — the authoritative number is whatever tools/list returns, which is 79. Ignore the banner.

How a tool call maps to HTTP

Every tool is a thin wrapper over one REST endpoint. The server (tools.ts → resolveToolPath) routes your arguments in a fixed, predictable way:

Path parameters — any argument whose name matches a {param} in the endpoint path (e.g. policy_id in /policies/{policy_id}/rules) is substituted into the URL.
Query string — on a GET tool, every remaining argument becomes a ?key=value pair.
JSON body — on a POST / PUT / DELETE tool, every remaining argument becomes a top-level field of the request body.

So create_rule with {policy_id, category, enabled, config} sends POST /policies/{policy_id}/rules with a body of {category, enabled, config} — policy_id never appears in the body. You never construct URLs yourself; you pass flat named arguments and the server does the rest.

Reading the field reference

Every tool below lists its complete argument set with type and whether it is required:

bold type — required (the API rejects the call without it).
plain type · opt — optional.

All arguments are hoisted to the top of the JSON-RPC arguments object. Types are the JSON Schema types declared in the shipped @phosra/mcp@0.4.0 source — the same schemas your MCP client sees in tools/list. Nested object shapes (create_rule.config, connect_platform.credentials, consult_advisor.context) are documented in Nested payload shapes below.

Tool reference

All 79 tools, grouped by domain. Each row links to the matching API reference page where one exists — that page documents the full response body, every field, and every status code for the underlying endpoint.

Account & quick setup

Tool	Arguments	HTTP · API reference
`get_current_user`	—	`GET /auth/me` · ref
`quick_setup`	`child_name` `string` `birth_date` `string` (YYYY-MM-DD) `strictness` `string` · opt `family_id` `string` · opt `family_name` `string` · opt	`POST /setup/quick`

quick_setup is the one-call onboarding path: it creates a family, adds a child, generates age-appropriate rules, and activates the policy. strictness is recommended (default), strict, or relaxed. Pass family_id to add the child to an existing family instead of minting a new one.

Families & members

Tool	Arguments	HTTP · API reference
`list_families`	—	`GET /families` · ref
`create_family`	`name` `string`	`POST /families` · ref
`get_family`	`family_id` `string`	`GET /families/{family_id}` · ref
`update_family`	`family_id` `string` `name` `string`	`PUT /families/{family_id}` · ref
`delete_family`	`family_id` `string`	`DELETE /families/{family_id}` · ref
`list_family_members`	`family_id` `string`	`GET /families/{family_id}/members` · ref
`add_family_member`	`family_id` `string` `user_id` `string` `role` `string` (`owner` \| `parent` \| `guardian`)	`POST /families/{family_id}/members` · ref
`remove_family_member`	`family_id` `string` `member_id` `string`	`DELETE /families/{family_id}/members/{member_id}` · ref
`family_overview_report`	`family_id` `string`	`GET /families/{family_id}/reports/overview`

Children

Tool	Arguments	HTTP · API reference
`list_children`	`family_id` `string`	`GET /families/{family_id}/children` · ref
`create_child`	`family_id` `string` `name` `string` `birth_date` `string` (YYYY-MM-DD)	`POST /families/{family_id}/children` · ref
`get_child`	`child_id` `string`	`GET /children/{child_id}` · ref
`update_child`	`child_id` `string` `name` `string` · opt `birth_date` `string` · opt	`PUT /children/{child_id}` · ref
`delete_child`	`child_id` `string`	`DELETE /children/{child_id}` · ref
`get_child_age_ratings`	`child_id` `string`	`GET /children/{child_id}/age-ratings` · ref

Policies

Tool	Arguments	HTTP · API reference
`list_policies`	`child_id` `string`	`GET /children/{child_id}/policies` · ref
`create_policy`	`child_id` `string` `name` `string` `priority` `integer` · opt	`POST /children/{child_id}/policies` · ref
`get_policy`	`policy_id` `string`	`GET /policies/{policy_id}` · ref
`update_policy`	`policy_id` `string` `name` `string` · opt `priority` `integer` · opt	`PUT /policies/{policy_id}` · ref
`delete_policy`	`policy_id` `string`	`DELETE /policies/{policy_id}` · ref
`activate_policy`	`policy_id` `string`	`POST /policies/{policy_id}/activate` · ref
`pause_policy`	`policy_id` `string`	`POST /policies/{policy_id}/pause` · ref
`generate_rules_from_age`	`policy_id` `string`	`POST /policies/{policy_id}/generate-from-age` · ref

Rules

Tool	Arguments	HTTP · API reference
`list_rules`	`policy_id` `string`	`GET /policies/{policy_id}/rules` · ref
`create_rule`	`policy_id` `string` `category` `string` `enabled` `boolean` `config` `object` — see config shapes	`POST /policies/{policy_id}/rules` · ref
`bulk_upsert_rules`	`policy_id` `string` `rules` `array<object>` — each `{category, enabled, config}`	`PUT /policies/{policy_id}/rules/bulk` · ref
`update_rule`	`rule_id` `string` `enabled` `boolean` · opt `config` `object` · opt	`PUT /rules/{rule_id}` · ref
`delete_rule`	`rule_id` `string`	`DELETE /rules/{rule_id}` · ref

Platforms & compliance links

Tool	Arguments	HTTP · API reference
`list_platforms`	—	`GET /platforms` · ref
`get_platform`	`platform_id` `string`	`GET /platforms/{platform_id}` · ref
`list_platforms_by_category`	`category` `string` (`dns` \| `streaming` \| `gaming` \| `device` \| `browser`)	`GET /platforms/by-category` · ref
`list_platforms_by_capability`	`capability` `string` — one of the 18 capability values	`GET /platforms/by-capability` · ref
`list_compliance_links`	`family_id` `string`	`GET /families/{family_id}/compliance` · ref
`connect_platform`	`family_id` `string` `platform_id` `string` `credentials` `object` — see credentials shape	`POST /compliance` · ref
`disconnect_platform`	`link_id` `string`	`DELETE /compliance/{link_id}` · ref
`verify_connection`	`link_id` `string`	`POST /compliance/{link_id}/verify` · ref

Enforcement

Tool	Arguments	HTTP · API reference
`trigger_enforcement`	`child_id` `string` `platform_ids` `array<string>` · opt	`POST /children/{child_id}/enforce` · ref
`list_enforcement_jobs`	`child_id` `string`	`GET /children/{child_id}/enforcement/jobs` · ref
`get_enforcement_job`	`job_id` `string`	`GET /enforcement/jobs/{job_id}` · ref
`get_enforcement_results`	`job_id` `string`	`GET /enforcement/jobs/{job_id}/results` · ref
`retry_enforcement`	`job_id` `string`	`POST /enforcement/jobs/{job_id}/retry` · ref

trigger_enforcement.platform_ids narrows the fan-out to a subset (e.g. ["netflix", "youtube"]); omit it and enforcement pushes to all connected platforms. Valid IDs: netflix, paramount_plus, youtube_tv, peacock, prime_video, youtube, nextdns, android, fire_tablet, apple_watch, fire_tv_stick.

Ratings

Tool	Arguments	HTTP · API reference
`list_rating_systems`	—	`GET /ratings/systems` · ref
`get_ratings_for_age`	`age` `integer`	`GET /ratings/by-age` · ref
`convert_rating`	`rating_id` `string`	`GET /ratings/{rating_id}/convert` · ref

Webhooks

Tool	Arguments	HTTP · API reference
`list_webhooks`	`family_id` `string`	`GET /families/{family_id}/webhooks` · ref
`create_webhook`	`family_id` `string` `url` `string` `events` `array<string>` — see event enum	`POST /webhooks` · ref
`test_webhook`	`webhook_id` `string`	`POST /webhooks/{webhook_id}/test` · ref

Sources (parental-control app adapters)

Tool	Arguments	HTTP
`list_available_sources`	—	`GET /sources/available`
`connect_source`	`child_id` `string` `family_id` `string` `source` `string` (slug) `credentials` `object` · opt `auto_sync` `boolean` · opt	`POST /sources`
`get_source`	`source_id` `string`	`GET /sources/{source_id}`
`list_child_sources`	`child_id` `string`	`GET /children/{child_id}/sources`
`sync_source`	`source_id` `string` `sync_mode` `string` · opt (`full` \| `incremental`)	`POST /sources/{source_id}/sync`
`push_source_rule`	`source_id` `string` `category` `string` `value` `object` · opt	`POST /sources/{source_id}/rules`
`get_source_guided_steps`	`source_id` `string` `category` `string`	`GET /sources/{source_id}/guide/{category}`
`list_source_sync_jobs`	`source_id` `string` `limit` `integer` · opt	`GET /sources/{source_id}/jobs`
`get_source_sync_results`	`source_id` `string` `job_id` `string`	`GET /sources/{source_id}/jobs/{job_id}/results`
`disconnect_source`	`source_id` `string`	`DELETE /sources/{source_id}`

Sources are the parental-control-app adapters (Bark, Qustodio, Kidslox, …). On the sandbox they are api_tier: guided, auth_type: none — connect them without credentials and drive setup through get_source_guided_steps. Managed sources that need credentials accept a credentials object on connect_source.

Brief (what changed in child-safety)

Tool	Arguments	HTTP
`list_brief`	`status` `string` · opt (`unread` \| `read` \| `acted` \| `dismissed`) `kind` `string` · opt (`legislation` \| `platform_capability` \| `csm_tier` \| `compliance_alert` \| `news`) `limit` `integer` · opt	`GET /brief`
`get_brief_item`	`id` `string`	`GET /brief/{id}`
`mark_brief_read`	`id` `string`	`POST /brief/{id}/read`
`dismiss_brief_item`	`id` `string`	`POST /brief/{id}/dismiss`
`mark_brief_acted`	`id` `string`	`POST /brief/{id}/acted`
`apply_brief_item`	`id` `string`	`POST /brief/{id}/apply`

apply_brief_item is the autonomous-loop write: it applies a Brief item’s proposed policy diff (only on items whose recommended_action.kind == "policy_diff"). Preview it first with dry_run_apply (below).

Decisions & provenance

Tool	Arguments	HTTP
`list_decisions`	`from` `string` · opt (RFC3339) `to` `string` · opt (RFC3339) `rule` `string` · opt `provider` `string` · opt `outcome` `string` · opt (`applied` \| `failed` \| `skipped`) `page` `integer` · opt `page_size` `integer` · opt	`GET /decisions`
`get_decision`	`id` `string`	`GET /decisions/{id}`
`list_unreviewed_agent_decisions`	`family_id` `string` `min_risk` `string` · opt (`low` \| `medium` \| `high`) `limit` `integer` · opt	`GET /families/{family_id}/unreviewed-decisions`
`mark_provenance_reviewed`	`family_id` `string` `provenance_ids` `array<string>` `reviewed_note` `string` · opt	`POST /families/{family_id}/unreviewed-decisions/review`
`query_decisions_by_law`	`family_id` `string` `law_id` `string` `since` `string` · opt (RFC3339) `include_reverted` `boolean` · opt	`GET /families/{family_id}/decisions-by-law`

query_decisions_by_law answers “show me everything we did because of KOSA” — pass law_id as a lowercase registry slug like kosa, coppa-2, or ca-sb-976.

Safe autonomy (preview, snapshot, revert)

Tool	Arguments	HTTP
`dry_run_apply`	`family_id` `string` `id` `string`	`POST /brief/{id}/dry-run`
`snapshot_policy`	`family_id` `string` `label` `string` `ttl_days` `integer` · opt (default 30, max 365)	`POST /families/{family_id}/snapshots`
`revert_to_snapshot`	`family_id` `string` `id` `string` `reason` `string`	`POST /families/{family_id}/snapshots/{id}/revert`

snapshot_policy before any bulk autonomous change; revert_to_snapshot atomically restores the captured policy graph if a change turns out wrong.

Streaming (Server-Sent Events)

Tool	Arguments	HTTP
`subscribe_brief_stream`	`family_id` `string` · opt (defaults to the token’s family)	`GET /families/{family_id}/streams/brief`
`subscribe_enforcement_failures`	`family_id` `string`	`GET /families/{family_id}/streams/enforcement-failures`
`subscribe_statute_registry`	`family_id` `string` `jurisdictions` `array<string>` · opt	`GET /families/{family_id}/streams/statute-registry`

Each returns a stream_url the agent connects to (with the same Bearer token) to replace a polling loop.

Federation (advisor agents)

Tool	Arguments	HTTP · API reference
`register_advisor_agent`	`slug` `string` `display_name` `string` `publisher_org` `string` `callback_url` `string` `public_key_pem` `string` (Ed25519 PEM) `key_id` `string` `capability_domains` `array<string>` `scope` `string` (`family` \| `global`) `scope_family_id` `string` · opt* `manifest_url` `string` · opt*	`POST /advisors` · ref
`consult_advisor`	`family_id` `string` `capability` `string` `context` `object` `advisor_id` `string` · opt	`POST /advisors/consult` · ref
`list_advisor_audit_log`	`family_id` `string` `advisor_id` `string` · opt `capability` `string` · opt `since` `string` · opt (RFC3339) `limit` `integer` · opt	`GET /families/{family_id}/advisor-audit-log`

register_advisor_agent has two conditionally required fields (marked · opt* above): scope_family_id is required when scope="family", and manifest_url is required when scope="global". consult_advisor calls a registered third-party advisor with an RFC 9421 Ed25519-signed request and writes an immutable audit row; list_advisor_audit_log returns those rows with preserved response signatures for non-repudiation.

Nested payload shapes

Four tool arguments are typed object / array<object> in the schema — the schema deliberately leaves them open because their shape depends on the rule category, platform, or capability. Here are the real, sandbox-verified shapes.

`create_rule` / `bulk_upsert_rules` `config`

config is a category-specific JSON object. create_rule.category must be one of Phosra’s supported rule categories — the shipped tool description names 45, and the canonical, per-category list is enumerated in the Create rule API reference. The table below is the real config emitted by quick_setup (captured live from list_rules against the sandbox) for the 20 categories in the recommended set — copy these shapes directly into create_rule:

`category`	`config` (real sandbox JSON)
`addictive_design_control`	`{"disable_streaks":true,"disable_autoplay":true,"disable_like_counts":true,"disable_daily_rewards":true,"disable_infinite_scroll":true}`
`age_gate`	`{"enabled":true,"min_age":13}`
`algo_feed_control`	`{"mode":"chronological"}`
`content_rating`	`{"max_ratings":{"csm":"10+","esrb":"E10+","mpaa":"PG","pegi":"7","tvpg":"TV-PG"}}`
`data_deletion_request`	`{"enabled":true}`
`dm_restriction`	`{"mode":"none"}`
`geolocation_opt_in`	`{"geolocation_allowed":false}`
`monitoring_activity`	`{"enabled":true}`
`notification_curfew`	`{"start":"20:00","end":"07:00"}`
`privacy_account_creation`	`{"require_approval":true}`
`privacy_profile_visibility`	`{"visibility":"private"}`
`purchase_approval`	`{"require_approval":true}`
`purchase_block_iap`	`{"block_iap":true}`
`social_chat_control`	`{"mode":"friends_only"}`
`targeted_ad_block`	`{"block_targeted_ads":true}`
`time_daily_limit`	`{"daily_minutes":120}`
`time_scheduled_hours`	`{"schedule":{"weekday":{"start":"07:00","end":"21:00"},"weekend":{"start":"08:00","end":"22:00"}}}`
`usage_timer_notification`	`{"interval_minutes":15}`
`web_filter_level`	`{"level":"moderate"}`
`web_safesearch`	`{"enabled":true}`

A single create_rule call, exactly as the agent sends it over tools/call:

{
  "name": "create_rule",
  "arguments": {
    "policy_id": "1444bd3d-a5ac-40ae-be33-e4b8c9a522b8",
    "category": "time_daily_limit",
    "enabled": true,
    "config": { "daily_minutes": 90 }
  }
}

bulk_upsert_rules takes the same objects in an array under rules:

{
  "name": "bulk_upsert_rules",
  "arguments": {
    "policy_id": "1444bd3d-a5ac-40ae-be33-e4b8c9a522b8",
    "rules": [
      { "category": "web_safesearch", "enabled": true, "config": { "enabled": true } },
      { "category": "time_daily_limit", "enabled": true, "config": { "daily_minutes": 90 } }
    ]
  }
}

`connect_platform` `credentials`

Shipped-schema caveat (verified against the live sandbox). The tool schema types credentials as an object, but the underlying POST /compliance endpoint currently deserializes credentials as a JSON string — the raw secret for the platform (e.g. a DNS provider’s API key). Passing an object is rejected:

// POST /compliance  {"credentials": {"api_key": "…"}}  →  400
{ "error": "Bad Request", "message": "invalid request body", "code": 400 }

Send the credential as a plain string instead — "credentials": "<api_key_or_oauth_token>". This mismatch is real in @phosra/mcp@0.4.0; it is tracked for a follow-up release. manual-auth platforms (most streaming and gaming platforms on the sandbox) need no credential at all — connect them and enforce through their guided setup.

Platforms advertise how they authenticate via list_platforms (auth_type is api_key, oauth2, or manual). The DNS providers (nextdns, controld, cleanbrowsing) are api_key; android and microsoft are oauth2; streaming/gaming platforms are manual.

`consult_advisor` `context`

context is a free-form JSON object whose keys are defined by the advisor’s declared capability — e.g. for a homework_focus capability:

{ "child_age": 12, "current_app": "tiktok", "time_of_day": "school_hours" }

The advisor receives this verbatim inside the RFC 9421-signed request body. context is passed straight through; Phosra never inspects it.

Enumerated argument values

Three arguments are typed as an open string / array<string> in the shipped schema but only accept a fixed set of values. Here is the full, source-verified enumeration for each.

`create_webhook` `events`

events is an array<string>. The schema does not constrain the members, but the census fires exactly five events today — subscribe only to these:

Event	Fires when	Scope
`policy.updated`	A child’s policy is (re)compiled after any rule/policy change	Family
`pack.adopted`	A standards pack is adopted for a child	Family
`pack.revoked`	A standards pack is removed from a child	Family
`pack.version.released`	A new version of an adopted pack is published	Family
`test`	You call `POST /webhooks/{id}/test`	Family

{
  "name": "create_webhook",
  "arguments": {
    "family_id": "a43d46db-583f-4073-aacd-0984f316e561",
    "url": "https://example.com/hooks/phosra",
    "events": ["policy.updated"]
  }
}

Do not subscribe to device.* or other speculative names. They are reserved/internal and never delivered — a subscription to them is silently inert, not an error. The authoritative, per-event payload shape, the X-Phosra-Signature HMAC scheme, and the delivery/retry contract are documented in the Webhook events guide.

`list_platforms_by_capability` `capability`

capability is a single string. It must be one of the 18 capability identifiers defined in the census (internal/provider/adapter.go). An unknown capability is not an error — the endpoint returns a JSON null (empty match), so validate against this list client-side:

Capability	Meaning
`content_rating`	Enforce age-based content rating ceilings (CSM / ESRB / MPAA / PEGI / TV-PG).
`time_limit`	Daily screen-time caps.
`scheduled_hours`	Allowed-usage windows (school hours, bedtime).
`purchase_control`	Gate or block purchases / in-app purchases.
`web_filtering`	Category/level web content filtering.
`safe_search`	Force safe-search on search engines.
`app_control`	Allow/block or age-gate individual apps.
`social_control`	DM/chat and social-interaction restrictions.
`location_tracking`	Location-sharing controls.
`activity_monitoring`	Usage/activity monitoring and reports.
`custom_blocklist`	Per-family custom domain/app blocklist.
`custom_allowlist`	Per-family custom domain/app allowlist.
`privacy_control`	Profile-visibility and account-creation privacy controls.
`algorithmic_safety`	Feed-algorithm controls (chronological, anti-addictive).
`notification_control`	Notification curfews and throttling.
`ad_data_control`	Targeted-ad and data-collection controls.
`age_verification`	Age-gate / age-assurance enforcement.
`compliance_reporting`	Generate statutory compliance reports.

// tools/call → list_platforms_by_capability
{ "name": "list_platforms_by_capability", "arguments": { "capability": "web_filtering" } }

// Real sandbox result (head) — every platform advertising the capability, with its full capability set.
[
  {
    "id": "fire_tablet",
    "name": "Amazon Fire Tablet",
    "category": "device",
    "auth_type": "manual",
    "capabilities": ["content_rating","time_limit","scheduled_hours","web_filtering","safe_search","app_control","purchase_control"]
  }
]

The same capabilities array is on every element of list_platforms and get_platform, so you can also filter client-side without a round-trip.

Tool results & the error format

This is the part most MCP integrations get wrong, so it is worth stating precisely. Each tool runs its HTTP request and returns the API’s JSON response as the content of a successful tools/call result. The Phosra MCP server (server.ts) sets the result’s isError flag from the HTTP status — it does not raise a JSON-RPC protocol error. A 403 or 404 therefore arrives inside a normal result, not as a transport-level failure your client would throw on:

// A tools/call result for a not-found policy — note isError, and the
// API's JSON body carried verbatim in content[0].text.
{
  "content": [
    { "type": "text", "text": "{\n  \"error\": \"Not Found\",\n  \"message\": \"policy not found\",\n  \"code\": 404\n}" }
  ],
  "isError": true
}

Your agent should branch on isError (or parse content[0].text and read code) — never assume a tool “threw.”

The error envelope

Every Phosra error body is the same shape (from pkg/httputil in the census). The three base fields are always present:

Field	Type	Meaning
`error`	`string`	HTTP status text, e.g. `"Not Found"`, `"Forbidden"`.
`message`	`string`	Human-readable, bounded reason (never a raw stack/DB string).
`code`	`integer`	Numeric HTTP status, e.g. `404`.

Rule-plane and OCSS Trust-Framework endpoints add two more fields on a governance rejection:

Field	Type	Meaning
`class`	`string`	Machine-readable failure class — one of the seven published wire classes, e.g. `standing_failure`, `not_found`, `signature_invalid`, `nonconformant`, `replay`, `malformed`, `scope_failure`.
`failed_step`	`string`	Present only on `standing_failure`: the §6.2 step that failed — one of `authority_binding`, `scope`, `unregistered_slug`, `band_exceeds_tier`.

Real error bodies (captured from the live sandbox)

These are unedited responses from https://phosra-api-sandbox-production.up.railway.app/api/v1:

// 401 — bad or revoked MCP token. Auth failures are plain text, not JSON.
// (Tool result: isError=true, content[0].text = "invalid mcp token")
invalid mcp token

// 404 — clean not-found. "Never a substitution" (§8.3.5).
{ "error": "Not Found", "message": "policy not found", "code": 404 }

// 403 — caller is not a member of the target family.
{ "error": "Forbidden", "message": "not a member of this family", "code": 403 }

A 403 standing_failure — emitted by rule-plane writes and by trigger_enforcement when the authority-holder’s §6.2 standing does not back the binding — carries the extra class + failed_step fields:

// 403 — OCSS standing failure (shape from pkg/httputil/ocss_errors.go).
{
  "error": "Forbidden",
  "message": "no active consent attestation backs the binding",
  "code": 403,
  "class": "standing_failure",
  "failed_step": "authority_binding"
}

Internal (500) errors always serialize a fixed, sanitized body — { "error": "Internal Server Error", "message": "internal error", "code": 500 } — with no class and no cause text. The real cause is logged server-side, never returned on the wire.

End-to-end worked example

This is a real, unedited round-trip against the hosted sandbox. Set up a child in one call, then read back the generated rules — chaining the returned IDs, exactly as an agent would.

1. Provision a child with `quick_setup`

{
  echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"demo","version":"1"}}}'
  echo '{"jsonrpc":"2.0","method":"notifications/initialized"}'
  echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"quick_setup","arguments":{"child_name":"Maya","birth_date":"2017-06-15","strictness":"recommended"}}}'
  sleep 3
} | npx @phosra/mcp \
      --api-key=phomcp_YOUR_TOKEN \
      --api-url=https://phosra-api-sandbox-production.up.railway.app/api/v1

The tools/call result content (real server output, trimmed to the head):

{
  "family": {
    "id": "a43d46db-583f-4073-aacd-0984f316e561",
    "name": "Maya's Family"
  },
  "child": {
    "id": "163884f8-589d-4f35-a8aa-54aa923a1856",
    "family_id": "a43d46db-583f-4073-aacd-0984f316e561",
    "name": "Maya",
    "birth_date": "2017-06-15T00:00:00Z"
  },
  "policy": {
    "id": "f3ca9353-15c7-43e0-b544-8195eb095cde",
    "child_id": "163884f8-589d-4f35-a8aa-54aa923a1856",
    "name": "Maya's Protection Policy",
    "status": "active",
    "version": 0
  },
  "rules": [ /* 20 age-appropriate rules — see next step */ ]
}

One call produced a family, a child, an active policy, and 20 rules — the recommended set for a 9-year-old.

2. Read the generated rules with `list_rules`

Feed the returned policy.id straight into the next tool:

echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_rules","arguments":{"policy_id":"f3ca9353-15c7-43e0-b544-8195eb095cde"}}}'
# …piped through the same initialize handshake as above

Real response (first two of the 20 rules):

[
  {
    "id": "d3f23d77-048c-46a2-ad03-c257765347af",
    "policy_id": "f3ca9353-15c7-43e0-b544-8195eb095cde",
    "category": "addictive_design_control",
    "enabled": true,
    "config": {
      "disable_streaks": true,
      "disable_autoplay": true,
      "disable_like_counts": true,
      "disable_daily_rewards": true,
      "disable_infinite_scroll": true
    }
  },
  {
    "id": "28a6701d-089f-4d6a-9c69-311225b5921d",
    "policy_id": "f3ca9353-15c7-43e0-b544-8195eb095cde",
    "category": "age_gate",
    "enabled": true,
    "config": { "enabled": true, "min_age": 13 }
  }
]

The full set spans 20 categories: addictive_design_control, age_gate, algo_feed_control, content_rating, data_deletion_request, dm_restriction, geolocation_opt_in, monitoring_activity, notification_curfew, privacy_account_creation, privacy_profile_visibility, purchase_approval, purchase_block_iap, social_chat_control, targeted_ad_block, time_daily_limit, time_scheduled_hours, usage_timer_notification, web_filter_level, and web_safesearch.

What it looks like in a real conversation

Once the server is wired into your client, this happens in plain language.

Setting up a new child

You: Set up parental controls for my 8-year-old, Maya, born June 15 2017. Claude: (calls quick_setup) Done — Maya now has an active protection policy with 20 age-appropriate rules: addictive-design controls off, a 13+ age gate, content ratings, a daily time limit, scheduled hours, and safe-search enforced. Want me to connect a device or DNS filter to enforce these?

Adjusting a rule

You: Her teacher needs her to reach youtube.com for homework. Allow it. Claude: (calls list_rules, then update_rule on the web-filter rule) Added youtube.com to Maya’s allowlist. Every other web filter stays in place.

A safe autonomous change

You: A new state law just dropped in my Brief — handle it, but let me undo it if I disagree. Claude: (calls snapshot_policy, then dry_run_apply) Snapshot pre-sb976 saved. The dry run would add 2 rule categories across 1 policy, nothing removed. (calls apply_brief_item) Applied. If you want it reverted, just say so and I’ll revert_to_snapshot.

Security & token lifecycle

Family-scoped. A token authorizes exactly one family. It cannot see or touch another family’s data.
Hashed at rest. Only the SHA-256 hash and an 8-character prefix are stored. Phosra cannot show you a token again after creation.
Revocable instantly. Revoking from the dashboard or DELETE /mcp-tokens/{id} takes effect on the agent’s next call.
Auditable. last_used_at updates on every authenticated call, and autonomous writes land in the Decisions provenance log — review them with list_unreviewed_agent_decisions.
Local execution. The server runs on your machine as a client subprocess; your token never leaves your environment except as a Bearer header to the Phosra API over HTTPS.

Troubleshooting

Symptom	Cause & fix
`Error: Phosra API key is required.`	No `--api-key` flag and no `PHOSRA_API_KEY` env var. Pass one.
`401 invalid mcp token`	Token is malformed, revoked, or from a different environment. Mint a fresh one; sandbox and production tokens are not interchangeable.
Tools call the wrong environment	Set `--api-url` explicitly. With no flag the server defaults to production (`https://prodapi.phosra.com/api/v1`).
Client shows no Phosra tools	Fully restart the client after editing its config — MCP servers are launched at startup. Confirm `npx @phosra/mcp` runs in a terminal first.
Startup log says `Registering 42 tools`	Cosmetic stderr banner in v0.4.0. The real count is 79 (`tools/list`).

Next steps

Authentication — how Bearer tokens and sessions work across the API.
Create / list / revoke MCP tokens — the control-plane endpoints behind the dashboard.
Quickstart — the same sandbox, driven by curl and the SDKs.

​How it works

​Step 1 — Get an MCP token

​Step 2 — Install

​Step 3 — Configure your client

​Step 4 — Verify the connection

​How a tool call maps to HTTP

​Reading the field reference

​Tool reference

​Account & quick setup

​Families & members

​Children

​Policies

​Rules

​Platforms & compliance links

​Enforcement

​Ratings

​Webhooks

​Sources (parental-control app adapters)

​Brief (what changed in child-safety)

​Decisions & provenance

​Safe autonomy (preview, snapshot, revert)

​Streaming (Server-Sent Events)

​Federation (advisor agents)

​Nested payload shapes

​create_rule / bulk_upsert_rules config

​connect_platform credentials

​consult_advisor context

​Enumerated argument values

​create_webhook events

​list_platforms_by_capability capability

​Tool results & the error format

​The error envelope

​Real error bodies (captured from the live sandbox)

​End-to-end worked example

​1. Provision a child with quick_setup

​2. Read the generated rules with list_rules

​What it looks like in a real conversation

​Setting up a new child

​Adjusting a rule

​A safe autonomous change

​Security & token lifecycle

​Troubleshooting

​Next steps

How it works

Step 1 — Get an MCP token

Step 2 — Install

Step 3 — Configure your client

Step 4 — Verify the connection

How a tool call maps to HTTP

Reading the field reference

Tool reference

Account & quick setup

Families & members

Children

Policies

Rules

Platforms & compliance links

Enforcement

Ratings

Webhooks

Sources (parental-control app adapters)

Brief (what changed in child-safety)

Decisions & provenance

Safe autonomy (preview, snapshot, revert)

Streaming (Server-Sent Events)

Federation (advisor agents)

Nested payload shapes

`create_rule` / `bulk_upsert_rules` `config`

`connect_platform` `credentials`

`consult_advisor` `context`

Enumerated argument values

`create_webhook` `events`

`list_platforms_by_capability` `capability`

Tool results & the error format

The error envelope

Real error bodies (captured from the live sandbox)

End-to-end worked example

1. Provision a child with `quick_setup`

2. Read the generated rules with `list_rules`

What it looks like in a real conversation

Setting up a new child

Adjusting a rule

A safe autonomous change

Security & token lifecycle

Troubleshooting

Next steps