# RationalBloks MCP Server

**Deploy production APIs in minutes.** 49 tools for projects, schemas, deployments, object storage, and graph data — delivered on infrastructure you own (self-host or your own BYOC cluster).

[![License](https://img.shields.io/badge/license-Proprietary-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![PyPI](https://img.shields.io/pypi/v/rationalbloks-mcp.svg)](https://pypi.org/project/rationalbloks-mcp/)

## What Is This?

RationalBloks MCP lets AI agents (Claude, Cursor, etc.) deploy production APIs from a JSON schema. No backend code to write. No infrastructure to manage.

```
"Create a task management API with tasks, projects, and users"
→ 2 minutes later: Production API running on Kubernetes
```

## Installation

```bash
# recommended — no install step, always the latest release
uvx rationalbloks-mcp@latest

# or install into an environment
pip install rationalbloks-mcp
```

## Quick Start

### 1. Get Your API Key

Visit [rationalbloks.com/settings](https://rationalbloks.com/settings) and create an API key.

### 2. Configure Your AI Agent

**VS Code** - Add to `.vscode/mcp.json` (Cursor: `.cursor/mcp.json` with a `mcpServers` key):

```json
{
  "servers": {
    "rationalbloks": {
      "command": "uvx",
      "args": ["rationalbloks-mcp@latest"],
      "env": {
        "RATIONALBLOKS_API_KEY": "rb_sk_your_key_here"
      }
    }
  }
}
```

**Claude Desktop** - Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "rationalbloks": {
      "command": "uvx",
      "args": ["rationalbloks-mcp@latest"],
      "env": {
        "RATIONALBLOKS_API_KEY": "rb_sk_your_key_here"
      }
    }
  }
}
```

---

**Remote (no install):** point any MCP client at `https://mcp.rationalbloks.com/mcp` (Streamable HTTP) with `Authorization: Bearer rb_sk_...`.

---

## 49 Tools

### Relational Read Operations (15 tools)

| Tool | Description |
|------|-------------|
| `list_projects` | List all your projects |
| `get_project` | Get project details |
| `get_schema` | Get current JSON schema |
| `get_user_info` | Get authenticated user info |
| `get_job_status` | Check deployment job status |
| `list_project_jobs` | A project's jobs, newest first, each with its outcome (kept for the life of the project) |
| `get_project_info` | Detailed project info with K8s status |
| `get_version_history` | Git commit history |
| `get_template_schemas` | Pre-built schema templates |
| `get_schema_reference` | Advanced schema features reference (`__policy__`, `computed`, `__constraints__`, `__audit__`) |
| `get_subscription_status` | Plan and usage limits |
| `get_project_usage` | CPU/memory metrics |
| `get_project_storage_usage` | Object-storage file count and bytes used vs limits |
| `list_project_files` | List uploaded files (metadata + public URLs) |
| `get_schema_at_version` | Schema at specific commit |
| `list_clusters` | List your BYOC resource pools (client-owned clusters) |

### Relational Write Operations (7 tools)

| Tool | Description |
|------|-------------|
| `create_project` | Create new project from schema (`cluster_id` of one of your BYOC pools is required; `backend_type` python or rust) |
| `update_schema` | Update project schema (`dry_run: true` previews the migration plan without saving) |
| `deploy_staging` | Deploy to staging environment |
| `deploy_production` | Deploy to production |
| `delete_project` | Delete project permanently |
| `rollback_project` | Rollback to previous version |
| `rename_project` | Rename project |

### Graph Schema Operations (11 tools)

| Tool | Description |
|------|-------------|
| `get_graph_schema` | Get graph project schema |
| `get_graph_template_schemas` | Pre-built graph schema templates |
| `get_graph_version_history` | Graph schema version history |
| `get_graph_schema_at_version` | Schema at specific version |
| `get_graph_project_info` | Graph project info with K8s/Neo4j status |
| `create_graph_project` | Create Neo4j graph project |
| `update_graph_schema` | Update graph schema |
| `deploy_graph_staging` | Deploy graph to staging |
| `deploy_graph_production` | Deploy graph to production |
| `delete_graph_project` | Delete graph project |
| `rollback_graph_project` | Rollback graph to previous version |

### Graph Data Operations (15 tools)

| Tool | Description |
|------|-------------|
| `create_graph_node` | Create a single node |
| `get_graph_node` | Get node by ID |
| `list_graph_nodes` | List nodes by entity type |
| `update_graph_node` | Update node properties |
| `delete_graph_node` | Delete a node |
| `create_graph_relationship` | Create a relationship |
| `get_node_relationships` | Get node's relationships |
| `delete_graph_relationship` | Delete a relationship |
| `bulk_create_graph_nodes` | Bulk create nodes |
| `bulk_create_graph_relationships` | Bulk create relationships |
| `search_graph_nodes` | Search nodes by property filters |
| `fulltext_search_graph` | Full-text search across all fields |
| `traverse_graph` | Traverse graph from a node |
| `get_graph_statistics` | Get graph statistics (counts) |
| `get_graph_data_schema` | Get deployed data schema |

---

## Schema Format

Schemas must be in **FLAT format**:

```json
{
  "tasks": {
    "title": {"type": "string", "max_length": 200, "required": true},
    "status": {"type": "string", "max_length": 50, "enum": ["pending", "done"]},
    "due_date": {"type": "date", "required": false}
  },
  "projects": {
    "name": {"type": "string", "max_length": 100, "required": true}
  }
}
```

### Field Types

| Type | Required Properties |
|------|---------------------|
| `string` | `max_length` |
| `text` | None |
| `integer` | None |
| `decimal` | `precision`, `scale` |
| `boolean` | None |
| `uuid` | None |
| `date` | None |
| `datetime` | None |
| `json` | None |

### Auto-Generated Fields

These are automatic - don't define them:
- `id` (UUID primary key)
- `created_at` (datetime)
- `updated_at` (datetime)

### User Authentication

Use the built-in `app_users` table:

```json
{
  "employee_profiles": {
    "user_id": {"type": "uuid", "foreign_key": "app_users.id", "required": true},
    "department": {"type": "string", "max_length": 100}
  }
}
```

---

## Frontend

For frontend development, use our NPM packages:

```bash
npm install @rationalbloks/frontblok-auth @rationalbloks/frontblok-crud
```

These provide:
- **frontblok-auth**: Authentication, login, tokens, user context
- **frontblok-crud**: Generic CRUD via `getApi().getAll()`, `getApi().create()`, etc.

---

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `RATIONALBLOKS_API_KEY` | Your API key (required for stdio; HTTP clients send it as a Bearer token per request) | - |
| `TRANSPORT` | `stdio` or `http` | `stdio` |
| `HOST` / `PORT` | Bind address for `TRANSPORT=http` | `0.0.0.0` / `8000` |
| `LOGICBLOK_URL` | LogicBlok gateway base URL | `https://logicblok.rationalbloks.com` |
| `RATIONALBLOKS_DEBUG` | Print full tracebacks on startup errors | unset |

---

## Support

- **Documentation:** [rationalbloks.com/documentation](https://rationalbloks.com/documentation)
- **Email:** support@rationalbloks.com

## License

Proprietary - Copyright 2026 RationalBloks. All Rights Reserved.

<!-- mcp-name: com.rationalbloks/mcp -->