@sima-prime/mcp-server

SIMA MCP Server

MCP server for SIMA developer and agent discovery (Level A) plus optional authenticated protection-offer creation (Level B).

Aligned to production OpenAPI 0.8.0 and @sima-prime/agent-sdk 0.2.0.

Purchase story (payment still outside MCP):

offer → purchase → payment-intent → confirm-payment → ACTIVE

Purpose

Safe MCP entry for Claude Desktop, Cursor, and assistants.

Hard limits — MCP must not:

• sign wallets or hold private keys,
• collect payment or move funds,
• call purchase / payment-intent / confirm-payment to activate certificates,
• approve claims or authorize payouts.

Capability levels

Level	What MCP does	Status
A	Discovery + concrete buy path (/enter + SDK pay steps)	Default
B	Optional POST /agent/protection/offer when env token is set	Opt-in
C	In-MCP payment / certificate activation	Not approved

Level A is guidance only. Level B offer-create is opt-in via environment variables. Payment remains outside MCP (SDK/wallet or https://sima-prime.com/enter).

Current Status

Version 0.1.7 (MCP-BUY-001).

Implemented tools:

• sima_get_capabilities
• sima_get_sdk_install
• sima_get_quote_flow
• sima_get_public_discovery_assets
• sima_get_safety_boundaries
• sima_create_protection_offer (Level B; requires SIMA_AGENT_ACCESS_TOKEN)

Placeholder tools (still NOT_IMPLEMENTED):

• sima_get_openapi
• sima_get_wallet_auth_flow
• sima_get_certificate_verification_flow
• sima_get_claim_flow

Environment variables (names only)

See .env.example.

Variable	Required	Purpose
SIMA_AGENT_ACCESS_TOKEN	Level B only	Agent JWT for POST /agent/protection/offer
SIMA_API_BASE_URL	Optional	Defaults to https://api.sima-prime.com

Obtain a token with @sima-prime/agent-sdk: requestWalletNonce → wallet sign (outside MCP) → verifyWalletSignature → accessToken. Docs: https://sima-prime.com/developers/public

Never commit real tokens. Never log or print token values.

Installation

Local workspace build:

pnpm --filter @sima-prime/mcp-server build

Tests (offline; mocked fetch for Level B):

pnpm --filter @sima-prime/mcp-server test

Local smoke test:

pnpm --filter @sima-prime/mcp-server smoke:test

Public npx command, after npm publication:

npx @sima-prime/mcp-server

Buy path (Level A)

Every implemented discovery response ends with a Buy path section:

• Human: https://sima-prime.com/enter (Quick Protect)
• Agent: install SDK → auth → getProtectionOffer → purchaseProtection → payment-intent → confirm-payment
• Explicit: MCP does not take payment; complete pay via SDK/wallet or /enter

Optional MCP shortcut for offer economics only: sima_create_protection_offer (Level B).

sima_get_quote_flow

Documents getProtectionOffer with asset-denominated protectedAmount, plus the Buy path section.

sima_get_public_discovery_assets

Public discovery URLs (llms.txt, AI catalog, OpenAPI, developers, etc.) plus buy CTA.

sima_get_safety_boundaries

Lists hard limits and Level A/B/C wording: offer creation optional; no payment/certificate activation in MCP.

sima_create_protection_offer (Level B)

Inputs align to agent commercial offer fields (chain, walletAddress, assetAddress, assetSymbol?, assetType, purchaseMode?, protectedAmount?, totalBudget?).

Behavior:

• If SIMA_AGENT_ACCESS_TOKEN is missing → clear CONFIGURATION_REQUIRED response with how to set env + obtain agent auth + Level A buy links (server does not crash).
• On success → POST {SIMA_API_BASE_URL}/agent/protection/offer with Bearer token; returns offer summary + next steps to pay outside MCP.
• On API errors → status/message only (tokens redacted).

MCP stops after the offer response. It never calls purchase, payment-intent, or confirm-payment.

Run Locally

Build first:

pnpm --filter @sima-prime/mcp-server build

Run the stdio MCP server from the local monorepo:

node packages/mcp-server/dist/index.js

Level B example (token via env — do not paste secrets into configs that get committed):

# PowerShell
$env:SIMA_AGENT_ACCESS_TOKEN="YOUR_AGENT_JWT"
$env:SIMA_API_BASE_URL="https://api.sima-prime.com"
node packages/mcp-server/dist/index.js

Test With Claude Desktop / Cursor / Claude Code

Same stdio wiring as before. After build, point the client at packages/mcp-server/dist/index.js (or npx @sima-prime/mcp-server after publication).

Ask for sima_get_quote_flow or sima_get_public_discovery_assets to see the Buy path. For Level B, set SIMA_AGENT_ACCESS_TOKEN in the MCP server environment.

Security Philosophy

MCP may optionally create a protection offer when configured.

It must not:

• accept private keys or seed phrases,
• sign wallet messages,
• store access/refresh tokens in files or logs,
• perform payments or move treasury funds,
• approve claims or authorize payouts,
• issue or activate certificates,
• call purchase / confirm-payment endpoints,
• call admin endpoints,
• write to a production database.

Local Telemetry

The MCP server writes local JSON Lines telemetry to:

packages/mcp-server/logs/mcp-events.jsonl

Telemetry path resolution:

• If SIMA_MCP_TELEMETRY_LOG_PATH is set, telemetry writes to that exact file path.
• If the current working directory is the SIMA repo root, telemetry writes to packages/mcp-server/logs/mcp-events.jsonl.
• If the current working directory is packages/mcp-server, telemetry writes to logs/mcp-events.jsonl.
• Otherwise, telemetry writes to ~/.sima/mcp-server/logs/mcp-events.jsonl.

Telemetry is local-only: no network reporting, no remote analytics, no database writes, no auth data collection. Tool arguments and tokens are never logged.

Disable telemetry:

SIMA_MCP_TELEMETRY=off node packages/mcp-server/dist/index.js

Smithery Deployment Notes

Known Issue: tools: [] Workaround (GRW-005, 2026-06-29)

Upstream bugs: smithery-ai/cli #787, #770

Workaround applied: bundle/manifest.json has "tools": []. Tools are discovered via live MCP introspection.

Publish command (current):

pnpm bundle
npx @smithery/cli mcp publish ./sima-mcp.mcpb -n shehab-mustafa/sima-mcp-server

(Do not publish until Mustafa approves.)

Current Limitations

• Remaining placeholder discovery tools are still NOT_IMPLEMENTED.
• Level B requires a caller-supplied agent JWT via env; MCP does not perform wallet signing.
• Level C (in-MCP payment) is out of scope.