@sima-prime/mcp-server

SIMA MCP Server

Standalone read-only MCP server for SIMA developer, agent, and machine-to-machine discovery.

Purpose

This package is the foundation for a future SIMA Model Context Protocol server.

It is intentionally separate from:

• services/auth-service
• apps/customer-portal
• apps/browser-extension
• production API behavior
• protection, claims, treasury, certificate, wallet, and payment logic

The goal is to give Claude Desktop, Cursor, GitHub Copilot, ChatGPT Apps, autonomous agents, and developer assistants a safe MCP entry point for understanding SIMA.

Current Status

Version 0.1.2 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.2
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 quote economics through the public SDK:

Package: @sima-prime/agent-sdk
Install: npm install @sima-prime/agent-sdk
SDK method: createProtectionQuote
Purpose: request quote economics only
Required fields: chain, walletAddress, assetAddress, assetSymbol, assetType, investedAmountUsd

The response includes a TypeScript example using SimaAgentClient.

Safety warnings:

quote does not issue certificate
quote does not collect payment
quote does not approve asset
quote does not approve claim
quote does not authorize payout

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:

• 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 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.

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,
• certificate verification flow,
• claim flow,
• public discovery assets,
• safety boundaries.

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