@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.0 is prepared for public npm distribution with two implemented read-only tools.

The server currently:

• starts over stdio,
• exposes MCP server metadata,
• registers placeholder tool names,
• logs startup to stderr,
• handles SIGINT/SIGTERM shutdown,
• 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_sdk_install
• sima_get_quote_flow

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 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 explicitly detectable.

Client detection is intentionally conservative. If SIMA_MCP_CLIENT or MCP_CLIENT_NAME includes claude, the client is recorded as Claude Code. If it includes cursor, the client is recorded as Cursor. Otherwise the client is Unknown MCP Client.

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