Documentation

Facilities MCP Documentation

Everything you need to get started with AI-powered engineering calculations, build your own tools, and earn royalties.

Getting Started

Get from zero to your first engineering calculation in under two minutes.

1

Create an account

Sign up at facilitymcp.patronusenergy.com/dashboard using your email or Google account. The free tier includes 50 MCP calls per month.

2

Generate an API key

Navigate to Dashboard → API Keys and click “Generate New Key.” Copy the key immediately — it won't be shown again.

api-key
pe_live_a1b2c3d4e5f6...
3

Configure your MCP client

Add the Facilities MCP server to your AI assistant's MCP configuration. Below is an example for Claude Desktop / Cursor:

json
{
  "mcpServers": {
    "facilities-mcp": {
      "url": "https://mcp.patronusenergy.com/sse",
      "headers": {
        "Authorization": "Bearer pe_live_YOUR_KEY_HERE"
      }
    }
  }
}
4

Run your first calculation

Ask your AI assistant to run an engineering calculation. The available tools will appear automatically in the assistant's tool list.

> “Size a 2" backpressure valve for 1000 MCFD natural gas at 0.62 SG”

 

Running kimray.gas_cv with GPSA sine-function method...

 

✓ Required Cv: 8.21

✓ Recommended: Kimray 2" 230 SGT (Cv max: 14.0)

Authentication

All MCP tool calls require a valid API key sent as a Bearer token in the Authorization header.

http
Authorization: Bearer pe_live_YOUR_KEY_HERE

Key Format

All keys start with pe_live_ followed by 48 hex characters. Keys are SHA-256 hashed before storage — we never store plaintext keys.

Key Limits

Free: 2 keys. Solo: 5 keys. Team: 20 keys. Revoked keys are permanently deactivated. Need more? Contact info@patronusenergy.com.

Rate Limiting

Free tier: 50 calls per month. Paid plans: unlimited. Tool authors can call their own tools without consuming quota.

IP Monitoring

Keys used from more than 3 distinct IPs within 24 hours are automatically flagged for review. This protects against key theft.

MCP Protocol

Facilities MCP implements the Model Context Protocol — the open standard for connecting AI assistants to external tools and data sources.

Transport

The server supports SSE (Server-Sent Events) transport at the /sse endpoint. Compatible with Claude Desktop, Cursor, and any MCP client that supports SSE.

Tool Discovery

Tools are dynamically registered from the Convex backend. When a builder publishes a tool and it passes admin review, it becomes available to all MCP clients automatically — no restart needed.

Tool Execution Flow

1AI assistant sends tool call request with parameters
2MCP server validates API key and checks quota
3Parameters are validated against the tool's input schema
4Formula code runs in a sandboxed Docker container
5If the tool has documents, vector search retrieves relevant context
6Results, instructions, and context are returned to the AI
7Usage is logged for billing and royalty tracking

Using Tools

Once connected, tools appear automatically in your AI assistant's tool list. Simply describe what you need and the AI will select and call the appropriate tool.

Tool Visibility

Public

Available to all authenticated users. This is the default for all published tools.

Org-Restricted

Only visible to members of the owning organization. Requires a Team or Enterprise plan.

Private

Only accessible to the tool author. Useful for testing before publishing.

Browsing Tools

Visit Dashboard → Tools to browse all published tools. Each tool card shows its description, input/output schema, version, and any attached standards references.

Builder Program

Builders are engineers who create and publish MCP tools on the platform. The builder program is open to anyone who applies and is approved by platform admins.

How to Apply

  1. Navigate to Dashboard → Builders Area
  2. Fill out the application form describing what you'd like to build
  3. Wait for admin review (typically 1-2 business days)
  4. Once approved, you get access to the full builder workspace

Royalty Model

50%

Creator Pool

25%

Platform Overhead

25%

Platform Operations

Your share = (your_tool_calls / total_platform_calls) × creator_pool

Payout Details

Schedule

Quarterly payouts calculated in January, April, July, and October.

Minimum

$25 minimum payout. Balances below threshold roll forward — you never lose earnings.

Method

Payouts via Stripe Connect. Set up your bank account in Dashboard → Earnings.

Exclusions

Builder self-calls are excluded. Minimum 25 qualifying calls per tool per quarter.

Building Tools

Tools are built from composable elements: datasets, formulas, documents, and workflows. The AI copilot helps you generate code and test cases.

Element Types

Dataset

Tabular data (valve catalogs, material properties, lookup tables). Editable in a spreadsheet-style UI.

Formula

Python functions that run in the sandbox. AI-generated from descriptions with automatic test case validation.

Document

PDF/text uploads that get chunked, embedded, and stored in the vector index. Retrieved at runtime via semantic search.

Tool

The published MCP tool definition. Combines formulas, datasets, documents, and instructions into a single callable tool.

Publishing Workflow

1Create a project and add your elements
2Use the AI copilot to generate and iterate on formulas
3Write or generate test cases and verify they pass
4Configure the tool element with input schema and instructions
5Submit for admin review
6Admin reviews code, tests, and content → approved or returned with feedback
7Published! Your tool is now live on the MCP server

Plans & Billing

Subscriptions are managed through Clerk Billing with Stripe as the payment processor.

FeatureFreeSoloTeam
Price$0/mo$47/mo$105/mo
MCP Calls50/moUnlimitedUnlimited
API Keys2520
Seats113
Private Tools——✓
Org Scoping——✓

Need enterprise pricing with custom seats, SSO, or a dedicated SLA? Contact info@patronusenergy.com.

View Full PricingManage Billing

Security

Security is built into every layer of the platform, from authentication to sandbox execution.

Authentication

Clerk handles user authentication with support for email, OAuth, and MFA. API keys use SHA-256 hashing — plaintext keys are never stored.

Sandbox Isolation

All formula execution happens in Docker containers with: network access disabled (--network=none), read-only filesystem, 256MB memory limit, non-root user, and 30-second timeout.

Internal API Protection

All server-to-server endpoints require an X-Internal-Secret header. No internal endpoint is accessible without it.

Content Review

Published tools go through admin review with automated scanning for prompt injection patterns, suspicious instructions, and XSS vectors.

IP Velocity Monitoring

API keys used from more than 3 distinct IPs in 24 hours are automatically flagged for review.

API Reference

The primary interface is the MCP protocol over SSE. For direct HTTP access, the following endpoints are available.

MCP Server

url
https://mcp.patronusenergy.com/sse

Server-Sent Events transport for the Model Context Protocol. Requires Bearer token authentication.

Health Check

bash
curl https://mcp.patronusenergy.com/health

Returns {"status": "healthy"} if the MCP server is running. No authentication required.

Key Validation

bash
curl -X POST https://your-convex-url.convex.site/api/validate-key \
  -H "Authorization: Bearer pe_live_YOUR_KEY_HERE"

Validates an API key and returns the associated user tier and permissions.