SIMA MCP Server

Read-only MCP server for SIMA developer and agent discovery.

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

Purchase story (API, not MCP execution):

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

sima_get_quote_flow documents getProtectionOffer with asset-denominated protectedAmount.

Purpose

Safe MCP entry for Claude Desktop, Cursor, and assistants. Does not call production APIs, sign wallets, move funds, issue certificates, approve claims, or execute payouts.

Current Status

Version 0.1.6 includes three implemented read-only tools and restored dashboard-compatible local telemetry path handling.

The server currently:

• starts over stdio,
• exposes MCP server metadata,
• registers placeholder tool names,
• logs startup to stderr,
• handles SIGINT/SIGTERM shutdown,
• returns server capability metadata from sima_get_capabilities,
• returns real SDK install metadata from sima_get_sdk_install,
• returns instructional quote-flow guidance from sima_get_quote_flow,
• returns NOT_IMPLEMENTED for every other tool call.

The server does not implement the remaining read-only discovery responses yet.

Installation

Local workspace build:

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

Local smoke test:

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

Public npx command, after npm publication:

npx @sima-prime/mcp-server

Pinned latest command, after npm publication:

npx @sima-prime/mcp-server@latest

Placeholder Tools

The package registers these MCP tools:

• sima_get_capabilities
• sima_get_sdk_install
• sima_get_openapi
• sima_get_wallet_auth_flow
• sima_get_quote_flow
• sima_get_certificate_verification_flow
• sima_get_claim_flow
• sima_get_public_discovery_assets
• sima_get_safety_boundaries

Implemented tools:

• sima_get_capabilities
• sima_get_sdk_install
• sima_get_quote_flow

sima_get_capabilities

It returns:

Package: @sima-prime/mcp-server
Version: 0.1.6
Safety class: PUBLIC_READ_ONLY
Purpose: Read-only MCP access to SIMA public developer, agent, and risk-protection integration information.
Implemented tools: sima_get_capabilities, sima_get_sdk_install, sima_get_quote_flow
Planned tools: sima_get_openapi, sima_get_wallet_auth_flow, sima_get_certificate_verification_flow, sima_get_claim_flow, sima_get_public_discovery_assets, sima_get_safety_boundaries

It also lists safety boundaries, including no transaction signing, no private key access, no certificate issuance, no claim approval, no payout authorization, no production mutation, and no production API calls.

sima_get_sdk_install

It returns:

SDK Name: @sima-prime/agent-sdk
Install: npm install @sima-prime/agent-sdk
Repository: https://github.com/Mustafashehab/SIMA-Agent-SDK
Documentation: https://sima-prime.com/developers/public
OpenAPI: https://sima-prime.com/openapi.json
AI Catalog: https://sima-prime.com/ai-catalog.json
Version: 0.1.0

sima_get_quote_flow

It returns read-only guidance for requesting asset-denominated protection offer economics through the public SDK:

Package: @sima-prime/agent-sdk
Install: npm install @sima-prime/agent-sdk
SDK method: getProtectionOffer
Purpose: request asset-denominated protection offer economics only
Required fields: chain, walletAddress, assetAddress, assetSymbol, assetType, protectedAmount

The response includes a TypeScript example using SimaAgentClient.

Safety warnings:

offer does not issue certificate
offer does not collect payment
offer does not approve asset
offer does not approve claim
offer does not authorize payout
offer does not expose USD or alternate currency fields

All other tools currently return:

NOT_IMPLEMENTED

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

The server logs startup details to stderr and communicates with MCP clients over stdio.

After npm publication, run the package through npx:

npx @sima-prime/mcp-server

Test With Claude Desktop

After building the package, add a local MCP server entry to your Claude Desktop configuration.

Example command:

{
  "mcpServers": {
    "sima": {
      "command": "node",
      "args": ["C:/Users/Admin/IdeaProjects/SIMA/packages/mcp-server/dist/index.js"]
    }
  }
}

Then restart Claude Desktop and ask it to list available SIMA MCP tools or call sima_get_sdk_install.

Expected result:

sima_get_sdk_install returns the public @sima-prime/agent-sdk install metadata.

Test With Claude Code

After npm publication, add the public stdio server with Claude Code:

claude mcp add --transport stdio sima -- npx @sima-prime/mcp-server

Before npm publication, add the local stdio server with Claude Code:

claude mcp add --transport stdio sima -- node C:/Users/Admin/IdeaProjects/SIMA/packages/mcp-server/dist/index.js

Then start Claude Code and inspect MCP servers:

/mcp

Test prompt:

Use the SIMA MCP server and show me how to install the SIMA Agent SDK.

Expected result:

npm install @sima-prime/agent-sdk

Test With Cursor

After npm publication, add this public package entry to Cursor's MCP configuration:

{
  "mcpServers": {
    "sima": {
      "command": "npx",
      "args": ["@sima-prime/mcp-server"]
    }
  }
}

Before npm publication, add a local MCP server entry to Cursor's MCP configuration.

Example:

{
  "mcpServers": {
    "sima": {
      "command": "node",
      "args": ["C:/Users/Admin/IdeaProjects/SIMA/packages/mcp-server/dist/index.js"]
    }
  }
}

Reload Cursor and ask the agent to call sima_get_sdk_install.

Expected result:

The SDK install tool returns package, install, repository, documentation, OpenAPI, AI Catalog, and version fields.

Security Philosophy

The MCP server starts read-only and public-discovery-only.

It must not:

• accept private keys,
• accept seed phrases,
• sign wallet messages,
• store access tokens,
• store refresh tokens,
• perform payments,
• move treasury funds,
• approve claims,
• authorize payouts,
• issue certificates,
• mutate backend records,
• write to a database,
• call admin endpoints.

Local Telemetry

The MCP server writes local JSON Lines telemetry to:

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

Telemetry path resolution is designed to work for both local repo runs and public npx runs:

1. If SIMA_MCP_TELEMETRY_LOG_PATH is set, telemetry writes to that exact file path.
2. If the current working directory is the SIMA repo root, telemetry writes to packages/mcp-server/logs/mcp-events.jsonl.
3. If the current working directory is packages/mcp-server, telemetry writes to logs/mcp-events.jsonl.
4. Otherwise, telemetry writes to the user-local fallback path ~/.sima/mcp-server/logs/mcp-events.jsonl.

Use the explicit path override when the admin dashboard needs to read MCP telemetry from a known repo path.

Windows local dashboard-compatible example:

$env:SIMA_MCP_TELEMETRY_LOG_PATH="C:\Users\Admin\IdeaProjects\SIMA\packages\mcp-server\logs\mcp-events.jsonl"
npx @sima-prime/mcp-server

VPS dashboard-compatible example:

SIMA_MCP_TELEMETRY_LOG_PATH=/root/SIMA/packages/mcp-server/logs/mcp-events.jsonl npx @sima-prime/mcp-server

The telemetry log path is only used locally by the MCP process. It is not returned in MCP tool responses.

Telemetry is local-only:

• no network reporting,
• no remote analytics,
• no database writes,
• no API calls,
• no auth data collection.

Tracked events:

• server startup,
• server shutdown,
• tool registration,
• tool invocation,
• tool name,
• duration,
• success/failure,
• NOT_IMPLEMENTED,
• ephemeral session ID,
• tool call sequence,
• client type when safely detectable,
• safe client name and version when provided by MCP initialization.

Client detection is intentionally conservative.

Detection sources:

• MCP initialization clientInfo.name and clientInfo.version, when provided by the client,
• optional environment hints: SIMA_MCP_CLIENT, MCP_CLIENT_NAME, SIMA_MCP_CLIENT_VERSION, MCP_CLIENT_VERSION,
• fallback: Unknown MCP Client.

Normalized client labels:

• Claude Code,
• Cursor,
• VS Code / GitHub Copilot,
• Unknown MCP Client.

Telemetry fields:

{
  "client": "Claude Code",
  "clientName": "Claude Code",
  "clientVersion": "1.2.3",
  "clientSource": "mcp_client_info"
}

If the client metadata is missing or ambiguous, telemetry keeps:

{
  "client": "Unknown MCP Client",
  "clientSource": "fallback"
}

Disable telemetry:

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

or:

SIMA_MCP_TELEMETRY_DISABLED=1 node packages/mcp-server/dist/index.js

Privacy guarantees:

• no private keys,
• no seed phrases,
• no wallet signatures,
• no access tokens,
• no refresh tokens,
• no auth headers,
• no cookies,
• no raw IP addresses,
• no hostnames,
• no usernames,
• no file paths,
• no prompts,
• no tool arguments,
• no request payload capture,
• no user fingerprinting.

Smithery Deployment Notes

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

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

Symptom: Publishing to Smithery with a populated tools array fails with:

Deployment failed: 400 {"error":"Invalid input: expected object, received undefined; Invalid input: expected object, received undefined; Invalid input: expected object, received undefined"}

Each "expected object, received undefined" corresponds to a tool entry missing its inputSchema when forwarded to the Smithery registry. The MCPB manifest schema does not include inputSchema on tool entries, so Smithery's registry rejects the payload.

Secondary symptom: Removing tools entirely causes the CLI to produce a serverCard with only name + version, which the registry rejects as "No values to set."

Workaround applied: bundle/manifest.json has "tools": [].

This satisfies the Smithery registry payload check without triggering the inputSchema validation. Tools are still fully functional — Smithery discovers them via live MCP introspection (the tools/list JSON-RPC method) when the server runs.

Side effect: The Smithery listing page shows "No capabilities found" in the static capabilities panel. This is cosmetic only. Live introspection returns all 9 registered tools.

Also affected: The long_description, homepage, and documentation fields in manifest.json are not forwarded by the current Smithery CLI to the registry listing. The server page will appear sparse until this CLI bug is fixed.

When to revert: Monitor the Smithery CLI changelog. When the inputSchema forwarding is fixed:

1. Restore the tools array in bundle/manifest.json with each entry including an explicit inputSchema field.
2. Re-run: pnpm bundle && npx @smithery/cli mcp publish ./sima-mcp.mcpb -n shehab-mustafa/sima-mcp-server
3. Update this note.

Publish command (current):

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

Current Limitations

This package does not:

• fetch SIMA public discovery assets,
• parse OpenAPI,
• call https://api.sima-prime.com,
• call https://sima-prime.com,
• use authentication,
• perform HTTP requests,
• expose production data,
• implement the remaining read-only MCP tool responses.

Future Roadmap

Future MCP milestones will implement read-only responses for:

• capabilities,
• OpenAPI URL,
• wallet authentication flow,
• quote flow,
• autonomous protection execution flow,
• protection policy schema,
• execution pipeline,
• protection runtime,
• reference integrations,
• developer playground,
• certificate verification flow,
• claim flow,
• public discovery assets,
• safety boundaries.

Planned read-only AP-1 capability:

sima_get_protection_execution_flow

This future MCP response will explain:

Quote
Payment
Certificate
Execute

It must remain documentation-only. MCP must not create quotes, collect payment, issue certificates, execute trades, approve claims, authorize payouts, score risk, or provide BUY/SELL/SAFE/UNSAFE guidance.

Planned read-only AP-2 capability:

sima_get_protection_policy_schema

This future MCP response will explain:

ProtectionPolicy
  -> evaluateProtectionPolicy()
  -> PROTECTION_REQUIRED or PROTECTION_SKIPPED
  -> executeProtectionPolicy()
  -> protectPosition() only when the caller-owned policy requires protection

It must remain documentation-only. MCP must not create, store, or modify policies; must not execute protection workflows; and must not describe assets as SAFE, UNSAFE, GOOD, BAD, BUY, SELL, or risk-scored.

Planned read-only AP-3 capability:

sima_get_execution_pipeline

This future MCP response will explain:

ExecutionPipeline
  -> ProtectionMiddleware
  -> ProtectionPolicy
  -> protectPosition()
  -> certificate fields injected into ExecutionContext
  -> caller-owned execution continues

It must remain documentation-only. MCP must not run pipelines, execute middleware, submit trades, mutate SIMA records, expose payment secrets, stop trades, change trade direction, or provide investment guidance.

Planned read-only AP-4 capability:

sima_get_protection_runtime

This future MCP response will explain:

ProtectionRuntime
  -> initialize()
  -> prepareExecution()
  -> protect()
  -> finalize()
  -> prepared execution context returned to caller-owned adapters

It must remain documentation-only. MCP must not initialize live customer runtimes, run protection workflows, call SIMA APIs, execute trades, mutate SIMA records, move funds, approve claims, authorize payouts, stop trades, change trade direction, or provide SAFE/UNSAFE/BUY/SELL guidance.

Planned read-only AP-5 capability:

sima_get_reference_integrations

This future MCP response will describe:

basic-position-protection.ts
autonomous-trading-bot.ts
wallet-integration.ts
treasury-automation.ts
execution-pipeline.ts

It must remain documentation-only. MCP must not run reference integrations, execute trades, call protected workflows, mutate SIMA records, sign wallets, move funds, approve claims, authorize payouts, recommend trades, or provide SAFE/UNSAFE/BUY/SELL guidance.

Planned read-only AP-6 capability:

sima_get_developer_playground

This future MCP response will describe:

/developers/playground
interactive protection flow
generated SDK code
generated MCP flow
reference integration links
certificate preview
policy builder
runtime visualizer
integration studio

It must remain documentation-only. MCP must not operate the browser playground, submit live quotes without caller authentication, generate fake API results, create certificates, execute trades, move funds, approve claims, authorize payouts, recommend trades, or provide SAFE/UNSAFE/BUY/SELL guidance.

Future phases may add local Claude Desktop, Cursor, and GitHub Copilot configuration examples after the read-only tools exist.