Centia Server

A Model Context Protocol (MCP) server that exposes the Centia API as MCP tools generated from the OpenAPI spec. It communicates over STDIO and can be used with any MCP-compatible client (Claude Desktop, MCP Inspector, etc.).

Prerequisites

• Node.js 18+ (20+ recommended)
• npm 9+

Install

# From the project root
npm install

Authentication

The MCP server uses the same login as the gc2-cli:

npm i -g @mapcentia/gc2-cli
gc2 connect https://api.centia.io   # only if not the default
gc2 login                            # browser, device, or password

The MCP server reads ~/.config/configstore/gc2-env.json (managed by gc2-cli) and refreshes the access token automatically when it expires.

For headless / CI use, set API_TOKEN (and optionally API_BASE_URL) — env vars take precedence over the stored session:

• API_BASE_URL (optional) — Base URL for the Centia API. Default: https://api.centia.io
• API_TOKEN (optional) — Static personal access token. Bypasses the stored gc2-cli session.

The API surface is defined in centia-api.json (already included in the repo). The server reads it at runtime to generate tools.

Run locally (development)

Hot‑reload development run with tsx:

npm run dev

This starts the MCP server on STDIO. It is meant to be launched by an MCP client (see below), but you can also smoke‑test it with the MCP Inspector.

Run with npx

You can run the server directly using npx.

If running from the source locally:

npm run build
npx .

If the package is installed or you want to use the published version:

npx @centia/mcp-server

Build and run (production)

npm run build
npm start

This compiles TypeScript to dist/ and starts node dist/index.js.

If you prefer a static token over the stored gc2-cli session (e.g. CI):

API_TOKEN=your_token_here npm start
# or
API_BASE_URL=https://api.centia.io API_TOKEN=your_token_here npm run dev

Using with MCP Inspector (recommended for local testing)

MCP Inspector lets you connect to the server and try tools interactively.

1. Start the Inspector UI:

   npx @modelcontextprotocol/inspector -- npx @centia/mcp-server
   

2. If needed, add environment variables in the Inspector connection dialog (e.g., API_TOKEN).

Using with Claude Desktop

Add the server to your Claude Desktop MCP config (e.g., claude_desktop_config.json).

Using npx (easiest)

{
  "mcpServers": {
    "centia": {
      "command": "npx",
      "args": ["-y", "@centia/mcp-server"]
    }
  }
}

Run gc2 login once and the server will pick up the session. To force a static token instead, add "env": { "API_TOKEN": "YOUR_CENTIA_TOKEN" }.

Using local source

{
  "mcpServers": {
    "centia": {
      "command": "npm",
      "args": ["run", "start"],
      "cwd": "/absolute/path/to/your/mcp-server"
    }
  }
}

• For development, replace "args": ["run", "start"] with "args": ["run", "dev"].
• Ensure cwd points to this project directory.

NPM scripts

• npm run dev — Run TypeScript directly with tsx (hot‑reload style dev loop).
• npm run build — Compile TypeScript to CommonJS/ESM in dist/ via tsc.
• npm start — Run the built server (node dist/index.js).

Using AGENTS.md and Skills with AI Coding Agents

This repository includes an AGENTS.md file with global hard rules and a skills/ folder with task-specific guidance for AI coding agents (like Claude Code, Junie, etc.) when working with Centia BaaS.

AGENTS.md contains the core rules (tool priority, security baselines, destructive-ops policy), while each skill in skills/*/SKILL.md covers a specific workflow area.

To ensure your AI agent follows these rules while developing your application:

1. Copy AGENTS.md and the skills/ folder from this repository to the root of your own application's repository.
2. When starting a session with your AI agent, it will automatically find and follow the guidelines.

AGENTS.md covers:

• Prime Directive: Preferring MCP tools and official SDKs.
• Tool Priority: Order of interaction (MCP tools > SDK > HTTP).
• Security & Auth: How to handle tokens and OAuth flows correctly.
• Destructive Operations Policy: Requiring explicit confirmation before destructive changes.

Skills (skills/*/SKILL.md) cover task-specific workflows:

• centia-runtime-sdk — Building JS/TS runtime code with @centia-io/sdk
• centia-provisioning — Schema, tables, columns, constraints, indexes, migrations
• centia-json-rpc — JSON-RPC method lifecycle and TypeScript interfaces
• centia-auth-model — Auth across browser, backend, CLI, and provisioning
• centia-types-formats — PostgreSQL types, casts, type hints, output formats
• centia-file-import — File import workflow
• centia-openapi-docs — OpenAPI and docs fallback policy
• centia-delivery — Delivery checklist and quality gate

Troubleshooting

• Tools missing or inputs look odd: ensure centia-api.json exists and is valid. The server generates tools from this file at startup.
• 401/403 errors: run gc2 login (or set a valid API_TOKEN in the environment for headless use).
• JSON Schema validation errors: schemas are auto‑normalized/sanitized for MCP, but if you updated centia-api.json, re-run and check logs for details.
• ESM/CommonJS issues: this project uses ESM ("type": "module"). Use Node.js 18+ and run scripts via npm as shown above.

License

ISC