MCP server

The Satia Remote MCP Server exposes a Satia workspace's full operational capabilities over the Model Context Protocol (MCP) Streamable HTTP (JSON-RPC 2.0) standard at /v2/mcp. It enables external engineering agents (Claude Code, Cursor, OpenAI Codex, Antigravity, Windsurf) to query, build, and operate inside Satia as first-class citizens.

1. Where to Find It in the Web Platform (/settings/mcp) & Security (satia_pat_...)

1. Web Configuration Page (/settings/mcp):
   • In the Satia web platform, users manage their MCP server access and view connection instructions at Settings > MCP (/settings/mcp) (https://satia.so/settings/mcp).
   • From /settings/mcp, each team member can generate, inspect, or revoke their own Personal Access Tokens (PAT).
2. Token Format & Secure Storage (satia_pat_...):
   • Keys use the satia_pat_... prefix, and only their SHA-256 hash (key_hash) is stored in mcp_api_keys — never the plaintext token.
   • The token can be passed via Authorization: Bearer satia_pat_..., X-Satia-Api-Key: satia_pat_..., or the ?api_key=satia_pat_... query parameter.
3. Strict RBAC Inheritance & Per-Workspace Isolation (caller_role = "mcp"):
   • Each satia_pat_... token is scoped to a specific (Workspace, User) pair. If a user operates across multiple companies or branches in Satia, they can generate one token per Workspace at /settings/mcp and register them in their IDE as "satia-company-a", "satia-company-b", etc.
   • The permission engine automatically enforces the exact same permissions that the user holds in the web UI: if the user is an Owner or Admin, they have full workspace access; if they are a Staff member, they can only read and modify the tables and modules granted in user_tables (configured at /settings/team).
4. Destructive Deletion Guardrail:
   • Record deletion tools are disabled on the MCP server by design (database__request_delete is exclusive to interactive chat with on-screen human confirmation). To deactivate a record from MCP, update its status column (estado = 'cancelado' / 'inactivo') or have the user confirm physical deletion in the Satia web UI.
5. Mandatory Human Attribution (user_prompt) & Shared Log with Sati:
   • All write and delegation tools on the MCP server require the user_prompt parameter containing the human instruction that triggered the action.
   • Every mutation is logged both in platform_audit_logs (reason = "[MCP: <YourKeyName>] <user_prompt>" and prompted_by = <user_id>) and in Sati's conversation history ([MCP • <YourKeyName>]), so whenever the user opens Sati on the web or Mobile App, Sati has full context of what was built or modified from the external MCP client.

2. How to Configure MCP in Each Agent / IDE

Replace <YOUR_SATIA_PAT_TOKEN> with your key generated at Settings > MCP (/settings/mcp):

A. Antigravity (~/.gemini/antigravity/mcp_config.json) or Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "satia": {
      "type": "http",
      "url": "https://apigateway-production-2b07.up.railway.app/v2/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_SATIA_PAT_TOKEN>"
      }
    }
  }
}

B. Claude Code (CLI or .mcp.json)

claude mcp add --transport http satia "https://apigateway-production-2b07.up.railway.app/v2/mcp" \
  --header "Authorization: Bearer <YOUR_SATIA_PAT_TOKEN>"

C. OpenAI Codex (~/.codex/config.toml)

[mcp_servers.satia]
url = "https://apigateway-production-2b07.up.railway.app/v2/mcp"
http_headers = { "Authorization" = "Bearer <YOUR_SATIA_PAT_TOKEN>" }

3. Recommended Workflow for MCP Clients

1. Load the Workspace Map on Session Start: Always call workspace__get_context() first to retrieve the active Workspace metadata (business_name, business_type, country, timezone), business tables catalog, system tables, Satia Docs folder tree (knowledge_folders), transactional assistants (agents), channels, and internal staff directory.
2. Inspect Columns Before Querying or Mutating: Call database__describe_tables(table_names=[...]) before executing database__query, database__insert, or database__update on any table whose columns you have not yet inspected.
3. Consult Manuals Before Building: Call discovery__get_manual(topic=...) and discovery__get_ui_design_manual(category=...) before building automations (automation_scripts), custom views (custom_views), schedules (schedules), or channels (channels).

4. Complete Catalog of Tools Exposed on the MCP Server

5. MCP Resources (resources/list & resources/read) & Public Documentation Endpoints

In addition to tools, the MCP server exposes all manuals as MCP Resources under the satia://docs/<topic> URI scheme (plus satia://skill/manual and satia://workspace/context), and serves public read-only HTTP endpoints:

• GET /v2/mcp/skill → Returns the main SKILL.md router skill in Markdown.
• GET /v2/mcp/manuals → Returns the JSON catalog of all official manuals.
• GET /v2/mcp/manuals/{topic} → Returns the Markdown content of any manual.
• GET /v2/mcp/llms.txt and GET /v2/mcp/llms-full.txt → Standard llms.txt index and full compiled documentation stream for LLMs.