@solidnumber/mcp

Model Context Protocol server for Solid# — the whole agent-attraction verb surface plus the platform REST tools, projected through stdio for any MCP- speaking agent runtime (Claude Desktop, Cursor, Cline, Codex, Windsurf, custom).

This server is for AI agents, not humans. The verbs are the product; this binary is the projection.

Install — 30 seconds

Claude Desktop / Cursor / Windsurf — one command (requires @solidnumber/cli):

solid mcp install claude     # or: cursor / windsurf / cline

Or add to claude_desktop_config.json directly (no CLI needed):

{
  "mcpServers": {
    "solidnumber": {
      "command": "npx",
      "args": ["-y", "@solidnumber/mcp"],
      "env": { "SOLID_API_KEY": "sk_solid_…" }
    }
  }
}

Or via claude mcp add (Claude Code):

claude mcp add solidnumber -- npx -y @solidnumber/mcp

SOLID_API_KEY is required. Without it the server still lists its full tool surface — the manifest is public — but every call is refused, because there is no anonymous tenant to run it against. Get a key at https://app.solidnumber.com/dashboard/install-command and put it in the env block above.

(Earlier versions of this file said the key was optional for reads and fell back to a public sandbox. That was never true, and it sent people into a wall of 403s on their first call.)

npm: https://www.npmjs.com/package/@solidnumber/mcp

What an agent loading this server gets

Two tool families. The larger is Solid#'s agent-attraction verbs — receipt-backed, rollback-safe, shape-typed action surface for AI agents. Thirteen shapes:

| Shape | Examples | What it gives the agent | |---|---|---| | Aggregate | customer_full_context, payment_full_history, order_complete_fulfillment_state | Collapse 5-8 sub-queries into one tenant-scoped read | | Explain | deal_explain_stage_change, crm_explain_contact_state, inventory_explain_stockout | Causal chain that produced a state | | Preview | payments_preview_refund_impact, subscription_preview_tier_change, infrastructure_preview_resize | Dry-run a write before commit | | Suggest | deal_suggest_next_action, customer_suggest_upsell, inventory_suggest_reorder | Ranked next-actions wrapped in the confidence envelope (confidence + confidence_band + reason + model_version + sample_size) | | Transaction | transaction_start, transaction_append, transaction_commit, transaction_abort | ACID grouping over multi-step writes | | Receipt | ucp_receipts_issue, voice_call_outbound, voice_send_sms | UCP-style attestations on side-effecting writes | | Revert | audit_revert | Single-action undo against whitelisted audit rows | | Subscribe | event_subscribe, event_poll, event_unsubscribe, event_list | Cursor-polling observe streams over AIAuditLog | | Discovery / Trail / Reputation / Macro / Telemetry | agent_manifest, agent_trails_lookup, agent_reliability_scoreboard, agent_macros_execute, agent_telemetry_status | Introspection + reliability + saved-chain promotion |

One name per operation (1.3.0). Where the platform spells one operation twice, the manifest marks the non-canonical name with same_as, and it is not listed — so an agent sees flows_create, not flows_create and flow_create. Every tool description starts its badge with the verb's Atlas address (atlas=37 crm), which is what separates two verbs whose descriptions read the same. Hidden names still work on tools/call.

The raw REST wrappers (one tool per backend route — post_crm_contacts, put_crm_deals_by_deal_id_stage, …) are off by default; they duplicate the verbs and carry generated descriptions. Opt in per install:

| env | effect | |---|---| | SOLID_MCP_RAW=1 | also list the raw REST route wrappers | | SOLID_MCP_ALIASES=1 | also list verbs that carry same_as |

The verb half is not baked into this package — it is fetched live from GET /api/v1/agent/verbs?surface=mcp_stdio and cached for 5 minutes, so new verbs reach an installed server without an npm republish. Ask the endpoint for the current count rather than trusting any number written down here — it moved from 587 to 624 in a single day while this file was being edited. That drift is why the old README and package.json disagreed (316 vs 169) while both were wrong.

Verb tour — what you can do in 60 seconds

# Read a customer's full context (orders, interactions, lifecycle, tickets)
solid agent dispatch customer_full_context --args '{"customer_id": 42}' --json

# Preview a refund without executing it
solid agent dispatch payments_preview_refund_impact --args '{"transaction_id": 100}' --json

# Diagnose a managed droplet's health
solid agent dispatch infrastructure_diagnose --json

# Get ranked next-actions for a deal
solid agent dispatch deal_suggest_next_action --args '{"deal_id": 7}' --json

# Check the live verb manifest (no auth)
curl https://api.solidnumber.com/api/v1/agent/verbs?surface=mcp_stdio

Every write verb returns an audit_id. Pass it to audit_revert to undo.

Sibling transports — same registry, four projections

This MCP server is one of four sibling transports projecting the same UNIFIED_VERB_REGISTRY. Adding a verb to the registry exposes it through all four within minutes (5-min cache TTL on this bridge):

                  UNIFIED_VERB_REGISTRY
                              │
     ┌──────────────┬─────────┴────────┬──────────────┐
    CLI         MCP stdio          WebMCP            UCP
 solid-cli   @solidnumber/mcp    in-browser    .well-known/ucp
                (this pkg)    navigator.modelContext

| Transport | Who uses it | Install | |---|---|---| | MCP stdio | Claude Desktop, Cursor, Windsurf, Cline | npx @solidnumber/mcp | | CLI | Claude Code, shell-running agents | npm i -g @solidnumber/cli | | WebMCP | In-browser agents (Chrome agent mode) | Automatic — every Solid# page ships verbs | | UCP | Buyer-agents (Gemini AI Mode, ChatGPT) | /.well-known/ucp discovery |

Parity is enforced by a backend integration test (tests/integration/test_sibling_transport_parity.py): a verb visible on one transport is visible on all four unless it explicitly omits the surface in its VerbRecord.surfaces declaration.

Auth model

| Tier | What the agent needs | What it gets | |---|---|---| | No key | — | tools/list only. Every call is refused; there is no anonymous tenant. | | Authenticated | SOLID_API_KEY env var | Read + write verbs against the key's bound tenant. Write verbs go through the same consent + idempotency + audit-log path as the dashboard. |

The MCP server is a thin projection. Multi-tenant isolation, consent gates, rate limits, and audit logging are all enforced server-side at /api/v1/agent/{namespace}/{verb} — never in this client. The bridge just forwards.

Receipt-backed ACID for AI agents

The reasoning loop the verb shapes support:

observe (aggregate) → explain → preview → commit (transaction/receipt)
                                                       │
                                                       ↓
                                                  audit_revert

An agent invoking a write verb gets back an audit_id. Pass that id to audit_revert and the action is undone (whitelisted handlers in the backend; unsupported types return a structured refusal with a machine-readable reason). Same architecture across every verb.

Live registry probe

A loaded agent can introspect the live verb manifest at any time:

GET https://api.solidnumber.com/api/v1/agent/verbs?surface=mcp_stdio

Returns the canonical JSON manifest the MCP bridge fetches every 5 minutes. New verbs land in tools/list within 5 minutes of shipping in the backend manifest — no @solidnumber/mcp republish required.

36 tool categories

CRM (contacts, deals, tasks, notes, tags) · Payments (invoices, refunds, payment links, disputes, payouts) · Voice (outbound calls, SMS, transcripts, translation) · Scheduling (appointments, Google Calendar) · CMS (pages, blog posts, brand engine) · Inventory (stock, allocation, reorder) · Infrastructure (droplet diagnose, resize, scale workers) · Subscriptions (tier upgrade/downgrade, seats, cancel) · GDPR (contact delete, data export) · Email (send, schedule, inbox read) · Analytics (web analytics, revenue reports) · Social (post create/schedule, platform management) · Integrations (connect, disconnect, status) · Agents (inter-agent messaging, mission dispatch) · Knowledge Base (create, update, search) · Workflows (trigger, list) · Audit (log access, revert) · Team (member management, campaign send) · Predict (deal-close, no-show, payment-late, target discovery) · and more.

Links

• npm: https://www.npmjs.com/package/@solidnumber/mcp
• Discovery: https://solidnumber.com/.well-known/mcp.json
• MCP endpoint: https://solidnumber.com/api/mcp
• Full verb JSON Schema: GET https://api.solidnumber.com/api/v1/agent/verbs?surface=mcp_stdio
• Docs: https://solidnumber.com/docs/mcp
• Spec: https://solidnumber.com/docs/spec
• Live manifest: https://api.solidnumber.com/api/v1/agent/verbs

License

BUSL-1.1 (converts to Apache 2.0 on 2030-04-14). Same license as @solidnumber/cli.

Author: Adam Campbell — Solid Number Inc.