# Philos: MCP and CLI setup

Philos connects a founder's partner program, partner readiness, purchase evidence,
earnings, and payment records. Read the same workspace data through MCP.

## Connect and authorize

1. Sign in to Philos and verify your identity. Connecting a client requires a verification within the last 15 minutes. If prompted, verify and return to the saved consent; callback, selected permissions and PKCE are preserved.
2. Open workspace Settings > Developer access and create a key with an authorized
   owner/admin account. Select Full Access (philos:full) to use all merchant workflows allowed by your current role. Keep the key private; it is shown once and stored hashed. Existing credentials keep their prior scopes. Partners select partner:full on their separate credentials.
3. Add the MCP connection to a compatible client:

       claude mcp add --transport http philos https://getphilos.ai/api/mcp \
         --header "Authorization: Bearer <your-key>"

Use the client's current MCP configuration instructions for other clients. The
endpoint speaks Streamable HTTP. API-key access is authenticated; OAuth clients
can discover the authorization metadata at
https://getphilos.ai/.well-known/oauth-authorization-server and request explicit consent.
Do not treat client support as a grant of workspace permissions.

## Full Access

An explicitly consented philos:full credential uses every delivered merchant workflow allowed by the issuing person's current role, including creating a workspace for a new site. Partner credentials use partner:full in their separate audience. Existing keys and OAuth grants keep their exact earlier permissions; reconnect or create a new credential to grant Full Access.

- operations_list: Discover every delivered Philos workflow available to this audience. Filter by domain or text. Returns stable operation IDs, execution/review modes, and pagination. Full Access never exceeds your current role.
- operation_schema: Get one operation contract, body fields and actions, path/query fields, audience, review mode and human-entry fields. The shared dashboard handler enforces the full input contract.
- operation_call: Call a discovered operation using the same Philos handler as the dashboard. Full Access ordinary work executes; consequential changes save an exact 15-minute review for the issuing person. Use the same request_id on retry; uncertain executions must be investigated before starting a new request. Secrets are entered only by the person on the review page. Specify workspace_id for another workspace you belong to. Files use {field,name,type,base64}. dry_run returns the authority/input preview without execution.
- operation_status: Recover a saved operation by request_id, without resending it. Returns its exact approved input and recorded result, failure, expiry or uncertain state. Only the issuing principal and credential audience can read it.

The generated catalog currently covers 189 merchant and 34 partner operations. It also identifies provider webhooks, identity proofs and internal endpoints with the workflow that supplies their authority. These cannot be invoked as ordinary agent actions. Full Access is product access through the same handlers and permission checks as the dashboard.

For example, discover POST /api/workspaces, then call operation_call with a stable request_id and body {action:"create",host:"goscratch.app",name:"GoScratch"}. Supply the returned workspace_id when saving a draft through POST /api/campaigns. Domain proof, billing and publication keep their respective evidence and review steps.

Ordinary work executes directly. Consequential operations save an immutable 15-minute review. The issuing person reviews the exact inputs and enters any confirmation or secret themselves. Secrets never enter the operation journal or an agent response. Current role, membership, credential, expiry, workspace revision and business versions are checked at execution. Recover an uncertain result with operation_status; inspect the business record before starting a replacement request.

Free signups use the Install Kit's signup_contract: signed brand_signup and creator_signup events go to /api/ingest/<workspace_id>/signup, with stable event_id, application customer_ref, occurred_at and the carried philos_ref. Read them through GET /api/conversions/signups. They never create a purchase, qualify a referral for earnings, or create a commission.

## Compatibility tools

This inventory is generated from the server's tool registry.

### workspace_overview (read)

Read workspace identity, plan and program/partner counts only. Financial and activity records require their separate scopes.

### campaign_list (read)

Paged campaign list: id, name, kind, status, currency, economics (rate, months, hold_days, amount_cents), commission model and basis, terms version and terms hash, destination URL and created time. Read-only. Returns rows, page, size, matching, has_more and as_of; use page to continue. Identity references and raw rejected-event payloads are omitted.

### partner_list (read)

Paged partner enrollment rows: status, campaign, code, per-currency balances and activity, with roster totals and application counts. Private identity references are stripped. Read-only. Returns rows, page, size, matching, has_more and as_of; use page to continue. Identity references and raw rejected-event payloads are omitted.

### conversions_recent (read)

Paged activity ledger rows, newest first: entry type, amounts, partner and campaign references, lifecycle state — plus per-currency gross/commission/reversal totals and the provider and currency summary. Read-only. Returns rows, page, size, matching, has_more and as_of; use page to continue. Identity references and raw rejected-event payloads are omitted.

### rejected_events (read)

Paged rejected ingest events — the integration debugger: replays, bad signatures, unattributed events and self-referral skips, each with its recorded reason. Read-only. Returns rows, page, size, matching, has_more and as_of; use page to continue. Identity references and raw rejected-event payloads are omitted.

### payout_status (read)

Payout state: the current payable assembly plus a bounded page of the batch history with statuses — size and a created_at/id cursor, matching the other paged reads. Read-only.

### partner_detail (read)

Single-partner relationship detail — the same projection the dashboard's relationship history uses: paged activity or payment rows for one enrollment, per-currency balances and integrity flags, minus the partner-private user reference. Requires partners:read; the payments kind needs director role. Read-only.

### event_explain (read)

One activity ledger entry explained — the same transaction receipt the dashboard renders: economic snapshot, evidence kind, receipts and adjustments for a single ledger id. Requires activity:read. Read-only.

### payment_batch_detail (read)

One payout batch with its items — the same batch detail the dashboard's payout review uses: status, totals, per-item state and amounts. Requires payouts:read; the item list needs admin role. Read-only.

### request_status (read)

Read a saved request's status and result by its request_id — the record only, never a resend. Returns the command id, tool, status (pending, executed, declined or expired), the exact preview, expiry and the recorded result for requests this credential's principal issued; a rotated credential resolves the same logical request through its key lineage. Available with workspace:read or any request scope. Read-only.

### install_kit (read)

The Install Kit for one program: the generated installation brief (markdown) and its machine-readable contract — ingest endpoints, required events, api_version, referral carry-through, signing recipe, fixture payloads and their expected commission. Contains no secret and writes nothing. Read-only.

### campaign_apply (write)

Request a pause, resume or program edit. The issuing person reviews exact before/after in Philos before anything changes. Pause requires director; live edits and resume require owner/admin. Draft editing and new publication use Program setup.

### partner_invite (write)

Request an invitation to a named program and email. An owner/admin reviews the recipient and offer in Philos before the enrollment or queued invitation is created. Delivery is recorded separately.

### partner_decide (write)

Request an application decision or enrollment change. The issuing person reviews the exact partner and action in Philos. Restriction or reinstatement requires owner/admin; application review requires director.

### payout_prepare (write)

Request an itemized manual payment proposal for review in Philos. Director or above. Approval prepares and reserves only the shown items; it never sends money or records payment. More than250 eligible rows requires the Payouts workspace.

## Review and authority

For compatibility write-named tools, show the human the exact object, recipient, action,
and relevant before/after or amount. Obtain explicit approval for that command.
Write-named tools save an expiring review request; they do not execute it.
Supply a UUID request_id and reuse it on retry. Set dry_run:true to inspect the
preview without saving a request or sending anything. The issuing person must
open the returned review_url, verify identity if requested, and approve the exact
preview in Philos. confirm:true cannot establish human approval. Changed records,
expired requests, revoked credentials and changed roles invalidate execution.
Compatibility tools use the credential's issuing workspace. Full Access may select another workspace only when the same person is an active member there.

payout_prepare requests review of a manual batch. Approval prepares the proposal;
it does not send money, prove payment,
or record a batch as paid. Money confirmation remains an explicit human action
in the app. An exported CSV is not payment confirmation. Partner-side tools such
as my_earnings are not in the current registry and must not be advertised.

## CLI

The CLI is distributed in this repository as cli/philos.mjs; there is no npm
installation command promised here. From a permitted source checkout:

       node cli/philos.mjs login --key <your-key> --url https://getphilos.ai
       node cli/philos.mjs status --json

Read commands: status, campaigns, partners, conversions, rejected, payouts,
install-kit. Review-request commands: invite, campaign pause|resume|edit,
partner approve|decline|suspend|terminate|reinstate, payout-prepare.
Use --dry-run to preview a request and --request-id <uuid> to retry it.
Write-named commands return the human review URL rather than claiming execution. The CLI stores a private configuration at ~/.philos.json. Never paste
its key into support messages, screenshots, or the conversation transcript.

## Revoke and recover

Create a key with the narrowest capabilities, a purpose and an expiry in workspace
Settings > Developer access. Rotate with a reviewed 30-minute or 24-hour overlap,
test the replacement with a read, then revoke the old key. Revocation takes effect
on future requests. A rotation cannot widen permissions.
A role change, suspension, revoked key, or expired consent can reject a request.
Investigate the reason; do not retry a write with broader credentials. For
uncertain results, inspect the existing record before repeating the command.

## Error classes

Every tool failure returns {ok:false, reason, class, retryable, server_request_id};
the response also carries an x-request-id header. class is one of the eight
contract values below; reason and retryable come from the server registry —
this table is generated from it. Unknown reasons classify as temporary_failure.

| reason | class | retryable |
| --- | --- | --- |
| already_completed | already_completed | no |
| ambiguous_delivery | indeterminate_provider_result | yes |
| approval_expired | stale_version | no |
| capability_unavailable | unavailable_capability | no |
| credential_revoked | expired_auth | no |
| destination_not_verified | invalid_input | no |
| enrollment_paused | unavailable_capability | yes |
| expired | expired_auth | no |
| expired_auth | expired_auth | no |
| forbidden | insufficient_role | no |
| insufficient_scope | insufficient_role | no |
| invalid_input | invalid_input | no |
| member_inactive | insufficient_role | no |
| migration_stale | stale_version | yes |
| not_found | invalid_input | no |
| nothing_payable | unavailable_capability | no |
| payment_paused | unavailable_capability | yes |
| prepared_items_changed | stale_version | yes |
| provider_result_unclear | indeterminate_provider_result | yes |
| replay_conflict | temporary_failure | yes |
| request_conflict | invalid_input | no |
| request_id_required | invalid_input | no |
| request_too_large | invalid_input | no |
| review_mismatch | invalid_input | no |
| review_required | unavailable_capability | no |
| revoked | expired_auth | no |
| service_unavailable | temporary_failure | yes |
| session_context_required | insufficient_role | no |
| stale_review | stale_version | yes |
| stale_version | stale_version | yes |
| structured_review_required | unavailable_capability | no |
| team_required | insufficient_role | no |
| temporary_failure | temporary_failure | yes |
| too_many_requests | temporary_failure | yes |
| unauthorized | expired_auth | no |
| unavailable_capability | unavailable_capability | no |
| uncertain | indeterminate_provider_result | yes |
| uncertain_payment | indeterminate_provider_result | yes |
| unknown_tool | invalid_input | no |
| unsupported_tool | unavailable_capability | no |
| use_program_setup | unavailable_capability | no |
| verification_required | insufficient_role | no |

server_request_id identifies the server-side request in logs and audit rows; it
is distinct from the caller-supplied request_id used for command idempotency.

Guide: https://getphilos.ai/agents
Help: https://getphilos.ai/help
Contact: hello@getphilos.ai