Claude & Model Context Protocol (MCP)

The Omnismith Model Context Protocol (MCP) Server enables seamless integration between your Omnismith workspaces and AI assistants like Claude Desktop, Google Antigravity, Cursor, and custom autonomous agents.

Through MCP, AI models gain first-class tools and dynamic resources to explore schemas, scaffold runtime data structures, query time-series metrics, and trigger automations on your behalf.

1. Claude Desktop Setup

Omnismith supports native OAuth 2.1 authentication for Claude Desktop. You do not need to manually generate or paste API keys into headers.

Option A: Native Custom Connector (Recommended)

In Claude Desktop, go to Customize → Connectors (or Settings → Connectors).
Click the + button next to Connectors and select Add custom connector.
Set the Name to Omnismith and enter the remote URL:
```
https://mcp.omnismith.io/mcp
```
Click Add. Claude Desktop automatically discovers OAuth 2.1 endpoints (RFC 9728) and opens your browser at the Omnismith Authorization Screen.
Select the Omnismith project you wish Claude to access and click Authorize.
Claude Desktop stores the session credentials and immediately unlocks Omnismith tools in your chat toolbar.

Option B: Claude Code CLI

If you use Claude from the terminal via Claude Code CLI, add the remote MCP server with:

claude mcp add omnismith https://mcp.omnismith.io/mcp

Follow the browser consent prompt to authorize your project.

Option C: Local Bridge & Config File

For environments using local bridge runners or configuration files:

Open your Claude Desktop configuration file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
Add the omnismith server configuration:

{
  "mcpServers": {
    "omnismith": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.omnismith.io/mcp"]
    }
  }
}

Restart Claude Desktop and authorize in the browser.

Option D: Programmatic API Key (Headless / CI/CD)

If you are running in headless CI/CD environments or tools where interactive browser consent is unavailable:

Open your workspace and navigate to Access & Security → Access Tokens.
Click Add Token to generate a programmatic access token (omni_live_...).
Pass the token in the authorization header:

{
  "mcpServers": {
    "omnismith": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.omnismith.io/mcp",
        "--header",
        "Authorization: Bearer omni_live_secret_key_demo"
      ]
    }
  }
}

2. Google Antigravity Setup

To connect Omnismith to Google Antigravity:

Add the server entry to ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "omnismith": {
      "serverUrl": "https://mcp.omnismith.io/mcp"
    }
  }
}

Open Antigravity and navigate to Settings → Customization → Installed MCP Servers.
Locate omnismith in the server list and click Sign In.
Complete authorization in your browser to bind your project workspace.

3. Remote Protocol Endpoints

Omnismith provides native Streamable HTTP transport for remote agents:

Resource	URL	Description
Streamable HTTP Endpoint	`https://mcp.omnismith.io/mcp`	Live JSON-RPC stream for tool execution and resource subscription.
Protected Resource Metadata	`https://mcp.omnismith.io/.well-known/oauth-protected-resource`	RFC 9728 discovery endpoint for OAuth 2.1 authentication.
Authorization Server Metadata	`https://mcp.omnismith.io/.well-known/oauth-authorization-server`	RFC 8414 metadata describing OAuth endpoints and token issuance.

4. Available Tools & Capabilities

When connected via MCP, your agent has access to a curated catalog of specialized operations:

📐 Schema & Modeling

scaffold_data_model: High-level synthesis tool to design and provision templates, attributes, and relationships in a single prompt, including form sections and the pinned metrics each record summarizes.
list_templates / get_template_details: Introspect data schemas, field bindings, and UI groups.
create_attribute / update_attribute: Create and configure dynamic attribute definitions.

📊 Records & Metrics

search_entities: Query and filter entity records across dynamic attributes.
aggregate_entities: Count, sum, average, min or max records, grouped by up to three attributes — answers “how many” and “broken down by” questions without paging through rows.
create_entity / update_entity: Create and update records according to template schemas.
batch_write_entities: Apply up to 100 mixed create, update, replace, delete and upsert operations in one call.
upsert_entity_by_key / get_entity_by_key: Write or read the record another system identifies by its own id — its External Key. The preferred way for an agent to write integration data: sending the same key twice never creates two records.
ingest_entity_metrics: Batch write time-series observations against entity records.
get_entity_chart: Query aggregated metric series with variable time windows.

⚡ Automations & Operations

list_automations / get_automation / create_automation / update_automation / toggle_automation: Inspect and configure Automations. This covers every trigger (record events, schedules, dates reached, no change within) and every action (notifications, update or create a record, run an entity action, HTTP request with response mapping).
list_automation_timers: List pending scheduled runs for a record (entity_id) or an automation (automation_id), soonest first. Use it to confirm a new date-reached or no-change automation actually scheduled the records you expected.
list_automation_executions: Read an automation’s runs, with per-action outcomes, due times and HTTP response details. Use it to check what an automation did.
list_notification_channels / create_notification_channel: Configure Telegram, Webhook or Push destinations; Webhook channels also serve HTTP request actions.
list_audit_logs: Query immutable project change records.

📥 Inbound Endpoints

Wire a live feed from Stripe, GitHub, a form tool or a device into a template — see Inbound Endpoints:

list_template_inbound_endpoints / get_template_inbound_endpoint: Inspect a template’s endpoints. get_schema_overview also lists them per template.
create_template_inbound_endpoint / update_template_inbound_endpoint / delete_template_inbound_endpoint: Configure the sender preset, mapping and delivery id.
preview_inbound_mapping: Dry-run a mapping — saved or not — on a sample payload, such as the example event in the sender’s documentation. Writes nothing.
add_inbound_endpoint_secret / delete_inbound_endpoint_secret: Rotate secrets.
list_inbound_deliveries / get_inbound_delivery: Read the delivery log to verify a test event or diagnose a rejected one.
replay_inbound_delivery: Re-run a failed delivery after the mapping is fixed.

A typical agent loop: create the endpoint with the sender’s preset, preview the mapping on a sample event, give you the URL and secret once for pasting into the sender, ask for a test event, read the delivery log, and fix and replay anything rejected. The secret is returned only when it is issued; agents are instructed not to repeat it or store it in a record.

🔘 Entity Actions

list_entity_actions: See which named operations a record’s template defines, and whether each is available right now.
execute_entity_action / batch_execute_entity_action: Run a defined Action on one record or a whole selection — its precondition and required fields are enforced the same way they are in the UI.

5. Security & Permissions

All MCP tool invocations execute under the security context of your authenticated Omnismith user and selected project:

Role-Based Access Control: The agent cannot perform operations exceeding your assigned workspace role permissions (Owner, Admin, Editor, Viewer).
Project Isolation: MCP sessions are strictly scoped to the project chosen during OAuth authorization.
Audit Logging: All record creations, schema modifications, and automation triggers executed via MCP are immutably logged to the project audit ledger.