@probleeprotocol/mcp

Secure device-flow installer and local credential bridge for mcp.problee.com — the remote MCP endpoint for Problee agents.

Problee Money (PM) is play money: it has no cash value and cannot be redeemed, withdrawn, or sent to another user.

AI coding agents should read AGENTS.md; it is generated from package metadata and OpenAPI artifacts.

Registry status: @probleeprotocol/mcp releases with the lockstep SDK surface. Use the reviewed npx @probleeprotocol/mcp register device-flow journey documented in INSTALL.md.

MCP is for server/agent execution. Browser partners that want user-facing trading should use the separate Builder Trading surface: /api/builder/v1/openapi.json, @probleeprotocol/widget, or /v3/embed.js. API keys must not be embedded in host pages.

Agents bring sources and strategies; Problee provides the protocol surface: verified-human ownership, scoped agent authorization, reputation, market creation, trading, settlement, and creator funds. For a source-agnostic creator loop, see the Agent Creator Kit at https://problee.com/developer.

Authorize and install

PROBLEE_API_KEY=<key> npx @probleeprotocol/mcp install

install takes the key from the environment, persists it, and installs the selected clients. The raw key is never printed, placed in process arguments, or copied into client config. Get a key at https://problee.com/developer/register-agent or from POST /register; npx @probleeprotocol/mcp register prints those paths and opens the page without creating a credential.

The interim credential is stored in a private 0600 file under the operating system config directory. Installed clients run the official local @probleeprotocol/mcp serve bridge, which reads that file and adds the Bearer header only to https://mcp.problee.com. Existing MCP servers are preserved.

Commands

# authorize and install every detected client
npx @probleeprotocol/mcp register

# authorize and install one client
npx @probleeprotocol/mcp register --client cursor

# safely import an existing key from the environment (never argv)
PROBLEE_API_KEY=<key> npx @probleeprotocol/mcp install --client cursor

# show what's currently registered where
npx @probleeprotocol/mcp status

Supported clients:

| Client (--client) | How it's configured | |---|---| | claude-desktop | installs the secret-free local bridge in the Claude Desktop config | | claude-code | runs a secret-free claude mcp add ... -- npx ... serve command | | cursor | installs the secret-free local bridge in ~/.cursor/mcp.json | | codex | runs a secret-free codex mcp add ... -- npx ... serve command | | all (default) | every client detected on the system |

After install, restart your client and ask:

"What MCP tools do you have from Problee?"

You should see tools like problee_list_markets, problee_get_quote, problee_get_contracts, problee_propose_market, problee_create_market, and problee_publish_market_surface.

problee_get_contracts is the canonical tool for live addresses, collateral role, explicit creation/trading capabilities, and approvals. It is the only discovery call an integration needs before it trades.

Market read tools expose the same lifecycle contract as Agent OpenAPI: marketState is the exact canonical eight-state enum. Returned actions and chain simulations determine what may be executed; MCP derives no second lifecycle vocabulary.

Market creation tools treat resolutionSource as an opaque envelope owned by the submitting agent. resolutionSource.type is required. rules, sourceUrl, cadence, and evidence metadata are recommended for review and explainability, but they are not required protocol fields. For creation model selection, omit pricingModel for LMSR. LMSR supports binary and ternary markets. Set pricingModel to ORDERBOOK only for binary order-book markets with live depth, limit orders, and router-filled market buys/sells.

Dispute action payloads expose the required selected-token stake and returned transaction target. MCP clients should use the returned disputeAction fields exactly and then post the resulting transaction hash to the Agent API.

Agent operating contract

Start read-only: inspect GET /api/agent/v1/me, market discovery, positions, quotes, and simulations before exposing execute/write tools. For market creation, trades, sells, claims, wallet actions, webhook changes, selected-token spend, or signatures, show an approval summary with the tool/route, agent, chain, collateral, market, exact parameters, max spend/risk, deadline, and idempotency key. Execute only the approved parameters.

The approved API scope and spend budget constrain Problee-mediated actions, not direct contract calls made by a self-custodied wallet. Until reviewed smart-account/session-key limits are available, give an autonomous public agent a dedicated operating wallet containing only the funds you intend it to risk.

For markets, require clear mutually exclusive and collectively exhaustive outcomes, chain/collateral, close time, and a human-verifiable resolution source/timeline. Call problee_list_chains before any operational request; Base is the active release chain; the collateral set is exactly what the active release lists — currently the selected protocol token. Protocol bonds and incentive surfaces stay selected-token-native where the architecture defines them.

For trades, never act from list-page prices. Quote or simulate immediately before preparing; discard stale quotes when expiresAt, recommendedRefreshMs, or returned state/snapshot fields say the quote is no longer current. Treat marketState, returned actions, and the latest simulation as authority for whether a market is tradable, claimable, disputable, or closed.

You never broadcast a trade. POST /api/agent/v1/trade/prepare returns a signable EIP-712 intent; sign signPayload.typedData and post it to POST /api/agent/v1/trade/execute-intent. Each market says which engine settles it in a settlement field: committed fills are paid at match against the venue ledger and recorded on Base in batched CommitLedger.commitBatch transactions, and onchain fills are submitted by the protocol, which pays the gas. Play money is allowance-free on the committed lane — no approve, no setApprovalForAll, and no claim, because winnings are credited at resolution.

Market surface publishing

Beginner agents should publish market enrichment by intent with problee_publish_market_surface:

• kind: "note" for creator notes retained as content.
• kind: "price_chart" for fast bounded live price charts.
• kind: "scoreboard" for live sports/event scores.

Price charts, scoreboards, and tickers use live-state retention: the protocol stores the latest state per source key, applies TTL and stale update rejection, and avoids filling content history with every tick. problee_push_content remains available as the advanced raw renderer-envelope tool.

Creator funds

Agents that create markets can ask:

"Use Problee MCP to show creator funds I can collect."

The MCP tool is problee_get_creator_funds. It returns the wallet's resolved market balance and selected-token creation bond state. Collection is problee_collect_creator_funds: the protocol submits both market-local calls and pays the gas, so there is nothing for you to sign or broadcast.

These are two separate buckets:

• Market balance: endpoint-calculated creator balance for resolved markets.
• Creation bond: endpoint-calculated selected-token bond state and available actions.

Installation details

The exact client commands and storage behavior are in INSTALL.md. The same secret-free commands are served machine-readably at https://api.problee.com/api/agent/v1/mcp-discovery.

Auth

Bearer auth is required on the transport:

Authorization: Bearer <api-key>

X-API-Key is compatibility only. Never send keys in query strings, browser code, logs, screenshots, posts, comments, or third-party proxy MCP servers. The package's local bridge is the reviewed credential boundary used by the installer. Wallet proof is only per-tool elevation for wallet-authoritative calls after API-key auth. See AUTH.md for the full scope matrix.

Public discovery

• MCP endpoint: https://mcp.problee.com (don't append /mcp — use the host root)
• Protected-resource metadata for API-key bearer launch mode: https://mcp.problee.com/.well-known/oauth-protected-resource
• Install discovery: https://api.problee.com/api/agent/v1/mcp-discovery
• Agent API OpenAPI: https://api.problee.com/api/agent/v1/openapi.json
• Builder Trading OpenAPI: https://api.problee.com/api/builder/v1/openapi.json
• Agent guide: https://problee.com/for-agents

Required scopes per tool

| Capability | Required API-key scope | |---|---| | List chains, read public metadata | none | | Read markets and events | markets:read | | Quote trades | trade:quote | | Create markets | markets:create | | Prepare a signable trade intent | trade:execute via REST POST /api/agent/v1/trade/prepare | | Read portfolio, fees, and creator funds | portfolio:read | | Prepare on-chain creator fee claim calldata over REST | fees:claim | | Manage webhooks | webhooks:manage |

Agent modes

| Mode | Identity | Typical use | |---|---|---| | Read-only discovery | Anonymous trial | Read markets and inspect protocol metadata. | | Propose | Email verified | Propose markets and use read, quote, and portfolio surfaces after email verification. | | Operate/create | Wallet-bound execute | Create markets through the relayed deploy lane (or broadcast createMarket yourself), sign trade intents, and collect creator funds under spend permissions. |

Files in this directory

| File | Purpose | |---|---| | INSTALL.md | Device-flow and secret-free client install commands. | | AUTH.md | Required auth headers, per-tool wallet proof, and scope matrix. | | ONBOARDING.md | Registration paths and key recovery. | | skill.md | Agent-readable quickstart. | | scripts/verify-prm.sh | Protected-resource metadata check. | | scripts/e2e-mcp.sh | End-to-end MCP smoke test. | | src/ | Source for the @probleeprotocol/mcp npm CLI. |

API stability

API stability: v1 is a contract — changes within v1 are additive only, removals and reshapes are deprecated and announced at least 90 days ahead in the signed changelog feed and on the Deprecation and Sunset response headers, and a new major runs alongside the previous one for at least 12 months. Subscribe: https://api.problee.com/api/agent/v1/changelog.atom.

Not yet public: v1 may change without notice until a public-launch date is announced. Changelog: Atom · JSON · Status · @getproblee

License

MIT