Positive Skew MCP

Native MCP tools for driving a Positive Skew account from Claude Desktop, Claude Code, Cursor, Codex, or any other MCP-aware client.

Safety Harness

The MCP server intentionally exposes no manual order-placement tool in paper or live modes. Use your broker or another execution surface for discretionary orders. In explicitly enabled full-owner mode, agents can inspect existing orders and cancel an order as a risk-reduction control; systematic executions continue to originate from the trading pipeline.

The server runs locally over stdio and reuses the same session file as the headless CLI:

~/.config/pskew/config.json

Quick Start

MCP 0.4.0, CLI 0.5.0, and Headless 0.4.0 are published on npm. Requires Node.js 22+. Agent sign-in uses the OS credential store: Keychain on macOS, Credential Manager on Windows, or an unlocked Secret Service with /usr/bin/secret-tool on Linux.

# Install both the CLI and the MCP binary
npm install -g @positive-skew/[email protected] @positive-skew/[email protected]

# Create a separate scoped profile; the owner reviews browser consent and MFA
pskew profile create agent
pskew agent signin

Next, use a manual registration below with the explicit agent profile, then restart your MCP client.

CLI 0.5.0's pskew mcp install registers the executable but does not persist PSKEW_PROFILE. Running it again can replace an entry's custom environment. Use the complete manual examples below for a profile-pinned setup; setting PSKEW_PROFILE only on the installer command is insufficient.

Keep the MCP registration pinned to PSKEW_PROFILE=agent using its env field. An agent-capability profile exposes exactly get_agent_account_snapshot and the static positive-skew://docs/agent-access guide. It does not register owner read tools, writes, feedback, portfolio resources, or owner workflow prompts.

The snapshot includes account identifier/mode, selected strategy settings, and simulated paper cash/equity only. No broker secrets, orders, live account balances, private strategy source, or account mutation is available. Access lasts at most seven days and stops on owner revocation or logout of the authorizing browser session. Refresh rotates the opaque capability; an uncertain refresh requires reauthorization with pskew agent signin, not retrying the old credential.

This is app-owned delegated access, not Supabase OAuth sign-in or a copy of the owner session. By default an owner profile exposes setup guidance only. Legacy password-authenticated owner mode requires explicit PSKEW_MCP_ALLOW_OWNER_SESSION=1 in the MCP registration environment. That grants FULL owner access, including existing account reads and confirmed mutations; it is not a read-only agent grant. Prefer the scoped profile for AI clients.

Manual Registration

If you prefer to wire things up by hand:

Claude Code

claude mcp add -s user positive-skew -e PSKEW_PROFILE=agent -- pskew-mcp

Claude Desktop

Add this to claude_desktop_config.json using an absolute path. Claude Desktop does not always inherit your shell PATH.

{
  "mcpServers": {
    "positive-skew": {
      "command": "/usr/local/bin/pskew-mcp",
      "env": { "PSKEW_PROFILE": "agent" }
    }
  }
}

Find the absolute path with which pskew-mcp.

Cursor

Add this to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "positive-skew": {
      "command": "/usr/local/bin/pskew-mcp",
      "env": { "PSKEW_PROFILE": "agent" }
    }
  }
}

Codex

Add this to ~/.codex/config.toml:

[mcp_servers.positive-skew]
command = "/usr/local/bin/pskew-mcp"
env = { PSKEW_PROFILE = "agent" }

Multiple Profiles

Create and authorize each scoped profile separately, then register one entry per profile with a PSKEW_PROFILE env override:

{
  "mcpServers": {
    "positive-skew-personal": {
      "command": "/usr/local/bin/pskew-mcp",
      "env": { "PSKEW_PROFILE": "agent-personal" }
    },
    "positive-skew-entity": {
      "command": "/usr/local/bin/pskew-mcp",
      "env": { "PSKEW_PROFILE": "agent-entity" }
    }
  }
}

Environment

The server uses the same Supabase configuration as the CLI. Positive Skew production is the default; these environment variables are optional explicit overrides:

• PSKEW_SUPABASE_URL and PSKEW_SUPABASE_ANON_KEY
• PSKEW_SUPABASE_ENV=staging
• PSKEW_SUPABASE_URL_STAGING and PSKEW_SUPABASE_ANON_KEY_STAGING
• PSKEW_PROFILE to select a profile
• PSKEW_MCP_ALLOW_OWNER_SESSION=1 to explicitly opt into FULL owner access for a legacy owner profile (disabled by default; unnecessary for scoped agent profiles)
• PSKEW_SESSION_PATH to override the absolute encrypted-session config path
• PSKEW_CREDENTIAL_STORE=file to explicitly opt into plaintext storage on a trusted headless host; default storage requires an OS credential store
• PSKEW_TELEMETRY=0 to disable optional telemetry headers

The MCP server does not load .env files from its current working directory. Pass overrides through the MCP client's env configuration.

Safety Model

The following describes legacy owner-session mode only. Scoped capability profiles use the narrower surface described above and cannot call these tools. Owner read tools use the owner's account permissions. Owner write tools default to dry-run and return a structured diff; confirm: true applies the change.

Every tool requires a rationale argument: a short explanation of the user intent behind the call. Do not include secrets, credentials, tokens, or private chat transcripts. Tools also expose optional context seeds such as analysis_focus, change_reason, trigger_reason, cancel_reason, and forecast_basis when that context helps Positive Skew understand the workflow.

Switching into live-alpaca requires both confirm: true and allow_live: true.

The server also exposes JSON resources for the current strategy, today's Skew, latest forecasts, and latest digest, plus positive-skew://docs/agent-guide for agent-specific operating instructions.

Feedback (full-owner mode only)

Agents can call report_agent_feedback when a workflow is blocked, confusing, or repeatedly requires awkward multi-tool stitching. The tool records what the agent was trying to do, which tools it tried, what happened, and what it expected so the MCP surface can improve over time.

Verify and troubleshoot

Run pskew mcp list to inspect registrations and PSKEW_PROFILE=agent pskew agent snapshot --json to verify the selected grant. Restart the MCP client after changing credentials or registration. A scoped session exposes get_agent_account_snapshot; an absent or disallowed owner session exposes only get_setup_instructions.

If the executable is not found, use the absolute path returned by which pskew-mcp (or where pskew-mcp on Windows). Examples above use a placeholder installation path; replace it with yours. A loopback timeout requires a fresh pskew agent signin on the browser's machine. Revoked, expired or uncertain-refresh sessions also require fresh owner approval. Quota errors include retry_after_seconds; wait before retrying the read.

Develop from source

Repository collaborators can run npm ci, npm run build:headless, npm run build:cli, and npm run build:mcp. For client registration, use command: "node", args: ["/absolute/path/to/positive-skew/mcp/dist/index.js"] and env: { "PSKEW_PROFILE": "agent" }. Keep the checkout available.