Skip to content
The Paraguay Plan

For staff

Work your queue from your assistant

The management MCP server lets Claude Code or Codex call the same audited management actions the staff portal uses. It runs on your machine, as you, with your own signed-in session. Nothing here bypasses the portal's permissions.

How it works

  1. Step 1

    Your assistant

    Claude Code or Codex starts the server as a local process and talks to it over stdio.

  2. Step 2

    The MCP server

    Validates every argument, then calls the management API over HTTPS with your staff token.

  3. Step 3

    The management API

    Authenticates you, checks your role and multi-factor level, and records every action with source=mcp.

The 21 tools

Case reads

  • cases_search
  • cases_get
  • cases_timeline

Paged in the database; cursors are bound to the filters that produced them.

Queue reads

  • queue_get_summary
  • queue_list

The same queue the portal shows, in pages of up to 100.

Document review

  • documents_list
  • documents_get_review_context
  • documents_decide

A decision needs a live review claim and an explicit "human review complete" assertion. OCR is advisory only.

Payment review

  • payments_list_pending
  • payments_get
  • payments_decide

Wire approval binds the exact payment and the exact amount.

Work and communication reads

  • tasks_list
  • case_emails_list
  • revenue_get_summary

Read-only.

Safe work mutations

  • cases_assign
  • cases_add_internal_note
  • cases_advance
  • tasks_create

Every mutation carries a request ID and is idempotent. Advancement performs only the canonical next step.

Controlled communication

  • communications_preview
  • communications_send
  • broadcasts_preview

Existing templates to the applicant on the exact case only. There is no broadcast send.

What it will never do

  • Read or change applicant accounts, or act as an applicant.
  • Download raw documents. Previews are 300-second image links, audited per grant.
  • Send free-form email, add recipients, or edit subjects and bodies.
  • Create, promote, deactivate or delete staff.
  • Delete cases, payments or documents.
  • Bypass an unknown mutation outcome by retrying with a new request ID.

Set it up

You need Node 22, a checkout of the repository, a staff account with authenticator enrolment, and the provenance capability from the platform operator. Choose your system and assistant; the commands below are generated for your paths.

Operating system
Assistant

  1. Build the server once

    cd "C:\Users\you\Code\paraguay-plan"
corepack pnpm install --frozen-lockfile
corepack pnpm mcp:build

  2. Write your staff token to an owner-only file

    Sign in to the staff portal, complete the authenticator challenge, and copy the session access token. It must have between five minutes and eight hours left. Save it as the only content of the file below and lock the file down. Never paste the token into a config file or a chat.

    # Write the token you copied, then restrict the file to your account only.
$tokenFile = "C:\Users\you\.tpp\staff.jwt"
New-Item -ItemType Directory -Force (Split-Path $tokenFile) | Out-Null
Set-Content -Path "$tokenFile.new" -Value "<paste token>" -NoNewline -Encoding ascii
icacls.exe "$tokenFile.new" /inheritance:r /grant:r "${env:USERNAME}:(R,W)"
Move-Item -LiteralPath "$tokenFile.new" -Destination $tokenFile -Force

  3. Export the environment

    $env:MCP_MANAGEMENT_RPC_URL = "https://manage.theparaguayplan.com/api/rpc"
$env:MCP_STAFF_ACCESS_TOKEN_FILE = "C:\Users\you\.tpp\staff.jwt"
$env:MANAGEMENT_MCP_INTERNAL_CAPABILITY = "<value from the platform operator>"
$env:MCP_REQUEST_TIMEOUT_MS = "15000"

    The provenance capability is issued by the platform operator. Ask for it directly; it is never published.

  4. Register the server in Claude Code

    claude mcp add --scope local paraguay-management --env MCP_MANAGEMENT_RPC_URL=$env:MCP_MANAGEMENT_RPC_URL --env MCP_STAFF_ACCESS_TOKEN_FILE=$env:MCP_STAFF_ACCESS_TOKEN_FILE --env MANAGEMENT_MCP_INTERNAL_CAPABILITY=$env:MANAGEMENT_MCP_INTERNAL_CAPABILITY --env MCP_REQUEST_TIMEOUT_MS=15000 -- node "C:\Users\you\Code\paraguay-plan\apps\mcp-server\dist\stdio.js"

  5. Verify

    claude mcp list
# then inside Claude Code: /mcp

    You should see exactly 21 tools. If the server refuses to start, the token is missing, expired, not AAL2, or the file permissions are too open. Fix the cause; do not retry blindly.

When a tool says no

token_expired
Your session token is missing, expired or invalid. Sign in again and replace the token file.
mfa_required
Complete the authenticator challenge in the portal; MCP requires an AAL2 session.
rate_limited
You are being throttled. The error carries retryAfterSeconds; wait that long.
conflict
The case is not in the state the action needs. Read it again before retrying.
mutation_outcome_unknown
The action may have happened. Do not retry with a new request ID; ask an operator to reconcile.
staff_access_required
The signed-in account is not an active case manager or admin.

Read-only API keys for integrations

Dashboards and automations that only need to read use the REST API with an API key rather than MCP. Administrators mint keys in the staff portal under Settings, then API keys. Every key expires between 30 days and 2 years after creation; rotate before expiry to keep an integration running without a gap. The key is shown once, at creation.

See what changed recently