Skip to main content

Agentic Development with GC2

Agentic development is a modern approach to software development where developers use AI agents to build applications through natural language and high-level abstractions. GC2 (Geo Compute Cloud) is built to be the perfect backend for this workflow, providing the tools and interfaces AI agents need to be productive.

What is Agentic Development?​

Agentic development isn't about writing every line of code yourself. It's about:

  • Natural Language First: Describing what you want to build and letting AI agents handle the implementation details.
  • Agent-Centric Workflow: Using tools like Claude Code, Junie, or Windsurf that can "understand" your project and make changes.
  • High-Level Abstractions: Focusing on the "what" and "why" while the AI handles the "how".

The @mapcentia/gc2-mcp-server package​

GC2 provides a dedicated Model Context Protocol (MCP) server that allows AI agents to interact directly with your GC2 backend. By connecting an AI agent to the @mapcentia/gc2-mcp-server server, you give it the ability to:

  • Manage Schemas: Create and modify tables, columns, indexes, and constraints.
  • Execute SQL: Run queries and mutations directly against your database.
  • Handle Auth: Manage users, rules, and OAuth clients.
  • Introspect: Allow the agent to explore your database structure to better understand your data.

An AI agent can build an app from scratch with the necessary data models and authentication logic.

Installing the MCP Server​

You can add the GC2 MCP server to your AI agent (like Claude Code or Junie) using the following configuration:

{
  "mcpServers": {
    "gc2": {
      "command": "npx",
      "args": ["-y", "@mapcentia/gc2-mcp-server"],
      "env": {
        "API_TOKEN": "your-access-token",
        "API_BASE_URL": "https://api.gc2.io"
      }
    }
  }
}

Configuration​

The server shares the configuration with the CLI, so you can just set the connection and login with CLI, and the MCP server is ready. But you can use the server without CLI, so the server accepts the following environment variables:

  • API_BASE_URL (optional) — Base URL for the GC2 API. Set it when using a self-hosted deployment. Default: https://api.gc2.io
  • API_TOKEN (optional) — Personal access token for GC2. Most endpoints/tools require authentication; set this to enable them.
info

Get your access token from the console.

Agent Guide (AGENTS.md and skills)​

To ensure AI agents work effectively with GC2, we maintain a AGENTS.md file and Skills folder. These contain "Prime Directives" and "Hard Rules" that help agents choose the right tools for the job, whether it's using the SDK for runtime code or MCP tools for provisioning.

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.
info

In Claude Code, copy AGENTS.md to CLAUDE.md, because Claude Code automatically reads CLAUDE.md.

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:

  • gc2-runtime-sdk — Building JS/TS runtime code with @mapcentia/gc2-sdk
  • gc2-provisioning — Schema, tables, columns, constraints, indexes, migrations
  • gc2-json-rpc — JSON-RPC method lifecycle and TypeScript interfaces
  • gc2-auth-model — Auth across browser, backend, CLI, and provisioning
  • gc2-types-formats — PostgreSQL types, casts, type hints, output formats
  • gc2-file-import — File import workflow
  • gc2-map-styling — Map view configuration and layer cartography (classes, styles, labels)
  • gc2-privileges — Sub-user privileges, groups and rights inheritance
  • gc2-openapi-docs — OpenAPI and docs fallback policy
  • gc2-delivery — Delivery checklist and quality gate

Key Takeaways for Agents​

When an agent is working in an agentic development environment with GC2, it follows these priorities:

  1. GC2 MCP tools: For schema changes and provisioning.
  2. @mapcentia/gc2-sdk: For application runtime logic.
  3. OpenAPI: For direct HTTP calls when needed.

By providing these clear instructions, GC2 ensures that developers and their agents can build robust, production-ready backends with minimal friction.