Skematia Protocol Specification v1.0

1. Overview

The Skematia Protocol is an open specification that enables AI agents and IDEs — Claude, Cursor, Windsurf, GitHub Copilot, custom autonomous agents, and any tool that wants to query, design, or operate on real databases — to connect to a production-grade backend with a single configuration step.

The protocol turns a database into a first-class citizen of the agent ecosystem: discoverable via Agent Card (A2A spec), operable via MCP (Model Context Protocol), and accessible via REST for any other client.

Why this exists

The current AI tooling landscape has a gap. Agents are powerful at reasoning and code generation, but their interaction with persistent data is limited to flat files, fragile shell commands, or one-off database wrappers. There is no shared, standard way for an agent to:

1. Discover what a database service can do.
2. Authenticate with a single credential that works across protocols.
3. Operate on the data — query, mutate, design schemas, evolve them safely.
4. Trust the result — with versioning, audit, rollback, and safety guards built in.

The Skematia Protocol fills that gap. It is to AI agents what JDBC was to Java applications — a uniform way to talk to a database, designed for the era of autonomous agents.

Architecture

2. Core Concepts

Project

An isolated Firebird 5.0 database. Each project has its own .fdb file, its own API key, and its own data.

API Key

A credential (sk_...) that identifies a client and associates it with a project. Sent as a Bearer token with every request.

Agent

Any software that connects: an AI bot, a desktop application, a Python script, a Node.js service — anything that speaks HTTP.

Transport

The protocol supports two transports, both MUST be implemented:

MCP (Model Context Protocol) — Primary transport for AI agents. JSON-RPC over HTTP, stateless mode.
REST API — Standard HTTP endpoints for traditional clients.

Both transports share the same authentication, reach the same Firebird engine, and respect the same permissions.

3. Discovery (Agent Card)

Every server MUST publish an Agent Card at GET /.well-known/agent.json following the A2A Protocol v0.2.6.

Example: skematia.com/.well-known/agent.json

4. Authentication

Every request MUST include an API key:

Authorization: Bearer sk_XXXXXXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXX

Permission Levels

Rate Limiting

Sliding window per API key. Response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Exceeding returns 429 Too Many Requests.

5. REST API

All endpoints use the /api/ prefix.

Data Endpoints

Schema Endpoints

SQL Safety Guards

Blocked by default: DROP TABLE, DROP DATABASE, TRUNCATE, DELETE without WHERE. Server responds 403 Forbidden.

Error Format

{
  "error": "Descriptive message",
  "error_type": "table_not_found",
  "hint": "How to fix it",
  "details": {}
}

6. MCP (Model Context Protocol)

Stateless HTTP transport at POST /mcp/. Each request is independent — no session management needed.

Available Tools (15)

Implicit API Key

If the API key is sent via Authorization header, it does not need to be included as a parameter in tool calls. Priority: explicit parameter > header.

Example Call

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "execute_sql",
    "arguments": {
      "project_id": "abc123",
      "sql": "SELECT * FROM CLIENTS ROWS 10"
    }
  },
  "id": 1
}

7. Schema Management

Versioning

Every DDL change is automatically recorded with timestamp, SQL executed, source, and agent. The history is immutable.

Schema Advisor

Automatic analysis with improvement suggestions: missing NOT NULL, missing UNIQUE, foreign keys without indexes, tables without primary keys. Each suggestion includes the SQL to apply it.

Assisted Migrations

Each migration generates up (apply) and down (revert) scripts. The down script is calculated automatically.

8. Firebird Notes

Each project is an independent .fdb file: individual backup with gbak, portable, no cross-project interference.

9. Security

Isolation: Each project has its own Firebird database. An API key can only access its bound project. Firebird is never exposed to the internet.

SQL Safety Guards: Destructive statements blocked by default (see section 5).

Audit Trail: All DDL operations recorded. DML operations optionally recorded.

Backups: Automatic daily backups, minimum 7-day retention, pre-restore backup required.

10. Connection Examples

Python

import requests
API_KEY = "sk_abc123_xxxxxxx"
PROJECT = "abc123-def456"
r = requests.post(
    f"https://skematia.com/api/data/{PROJECT}/raw-sql",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"sql": "SELECT * FROM CLIENTS ROWS 10"}
)
print(r.json()["results"])

Claude Desktop (MCP)

{
  "mcpServers": {
    "skematia": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://skematia.com/mcp/",
        "--header",
        "Authorization: Bearer sk_YOUR_API_KEY"
      ]
    }
  }
}

cURL

curl -X POST https://skematia.com/api/data/PROJECT_ID/raw-sql \
  -H "Authorization: Bearer sk_abc123_xxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT * FROM CLIENTS ROWS 10"}'

Node.js

const res = await fetch(`${API_URL}/data/${PROJECT}/raw-sql`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ sql: "SELECT * FROM CLIENTS ROWS 10" })
});
const data = await res.json();

11. Protocol Versioning

Semantic versioning: MAJOR.MINOR.PATCH. A server declaring v1.x MUST maintain compatibility with all v1.0 clients. Deprecated endpoints remain functional for at least 6 months before removal in the next MAJOR version.

12. Conformance Levels

Appendix: Design Decisions

Why Firebird: 25+ years of development, ACID compliant, single-file portability, no per-use licensing, native replication in v5.0. Ideal for intermittent connectivity scenarios.

Why Stateless MCP: Eliminates Redis dependency for sessions. Horizontal scaling without coordination.

Why API Keys (not OAuth): Simple, predictable, works identically across all languages. OAuth can be added later without breaking existing auth.

Why REST + MCP: REST is universal. MCP is the emerging standard for AI agents. Supporting both allows legacy and modern clients to connect with equal ease.

Roadmap (future extensions)