VS Code MCP Server
The AN5 ORM Schema Tooling extension (an5-orm-vscode) ships a native Model Context Protocol (MCP) server over standard I/O (stdio).
This server bridges your database models, SQL execution engine, and schema workflows directly to AI agent assistants—including GitHub Copilot in VS Code, Cursor, Claude Desktop, and any standard MCP client.
Architecture & Integration Flow
flowchart TD
subgraph Clients["1. AI Agent Clients"]
Copilot["GitHub Copilot (VS Code)"]
Cursor["Cursor IDE (MCP)"]
Claude["Claude Desktop"]
end
subgraph Server["2. AN5 ORM MCP Server (dist/mcp/server.js)"]
RO["8 Read-Only Inspection Tools<br/>(readOnlyHint: true)"]
Mut["5 Mutating Operations<br/>(confirm: true required)"]
Safety["Safety Guards: Path Traversal & SQL Read Guard"]
end
subgraph Runtime["3. Workspace & Database Execution"]
Workspace["Workspace Context<br/>(an5Schema/*.an5 · an5Orm.config.js)"]
Engine["Database & Engine<br/>(@an5/adapters · @an5/orm)"]
end
Clients -->|"JSON-RPC (stdio)"| Server
Server --> Workspace
Server --> Engine
1. Quick Setup & Discovery
The extension registers an automatic mcpServerDefinitionProviders handler. No configuration file needed.
-
Ctrl+Shift+POpen Command Palette -
MCP: List ServersBrowse available servers -
Start AN5 ORMClick to run immediately
Writes resolved execution paths into .mcp.json or .vscode/mcp.json preserving other servers.
-
AN5: Install MCP ServerGenerate workspace config -
AN5: Show MCP Server ConfigInspect JSON definition -
Status Bar > AN5 ORMOne-click quick actions
Sample Generated Workspace Configuration
When running AN5: Install MCP Server or inspecting via AN5: Show MCP Server Configuration, the server outputs the exact path to the active extension bundle:
{
"mcpServers": {
"an5-orm": {
"type": "stdio",
"command": "/usr/bin/node",
"args": [
"~/.vscode/extensions/an5orm.an5-orm-vscode-1.2.0/dist/mcp/server.js"
],
"cwd": "${workspaceFolder}"
}
}
}
Runtime Execution Note: The server uses Node.js to launch the script. System Node and version manager binaries (
nvm,fnm,volta,asdf) are fully supported. When running inside VS Code, the extension automatically discovers the host runtime path.
2. Workspace Context Discovery
When started, the MCP server analyzes your repository environment without requiring manual CLI arguments:
- Configuration: Evaluates
an5Orm.config.jsoran5Orm.config.cjsto locateschemaDir(defaults toan5Schema/). - Schema Files: Scans
.an5files up to 4 directory levels deep, filtering outnode_modules,.git,dist, andtarget. Ifan5Schema/is empty, it falls back to scanning the project root. - Database URL: Automatically reads
DATABASE_URLfrom active process environment variables or parses the workspace.envfile. - Local Engine: Detects the project’s installed
@an5/ormand@an5/adapterspackages to ensure scripts run against the project’s exact dependency versions.
3. Tool Reference (13 Tools)
Tools are organized into two distinct safety tiers:
an5_list_modelsOverview of all modelsan5_describe_modelFields, types, relationsan5_get_relationsRelation graph (FK/LK)an5_analyze_schemaAudit keys, indexes, auditan5_read_schema_fileRead raw .an5 filean5_describe_tableColumns & constraintsan5_database_healthLatency & connection checkan5_query_databaseRead-only SELECT / CTE
an5_generate_clientTS/Python/.NET/Go/Rustan5_push_schemaAdditive DDL push to DBan5_pull_schemaIntrospect DB into .an5an5_migratediff, apply, rollbackan5_seedExecute db:seed script
Detailed Tool Specifications
| Tool | Parameters | Description |
|---|---|---|
an5_list_models |
(none) | Returns the total count, physical table mapping, and field/relation summaries for every declared model. |
an5_describe_model |
model: string |
Returns full field metadata (sqlType, optional, primaryKey, unique, hasDefault, description) and relation connections. |
an5_get_relations |
(none) | Returns an edge array representing foreign-key and local-key links between models (one-to-many, many-to-one). |
an5_analyze_schema |
(none) | Runs automated static analysis: flags missing primary keys, unindexed foreign keys, and missing audit timestamps (createdAt, updatedAt). |
an5_read_schema_file |
file: string |
Returns full raw text of a .an5 file. Validates that the target path is strictly within the workspace root to prevent path traversal. |
an5_describe_table |
table: string |
Checks the schema model first; if absent, inspects physical database metadata directly. |
an5_database_health |
(none) | Performs a round-trip connection probe, reporting connection state and latency in milliseconds. |
an5_query_database |
sql: string |
Executes read-only queries. Permits single-statement SELECT and read-only CTEs (WITH ... SELECT). Rejects multi-statements and mutation keywords (INTO, INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, TRUNCATE, EXEC). |
an5_generate_client |
language: string, outputDir?: string, confirm: boolean |
Triggers the code generator for typescript, python, dotnet, golang, rust, java, kotlin or swift. |
an5_push_schema |
confirm: boolean |
Executes an additive schema sync (db:push) to create tables and add missing columns. |
an5_pull_schema |
confirm: boolean |
Overwrites local .an5 schemas with introspected database structure (db:pull). |
an5_migrate |
action: string, steps?: number, preview?: boolean, confirm: boolean |
Manages schema migrations: diff, generate, apply, rollback, or status. |
an5_seed |
confirm: boolean |
Populates the connected database using the project seed script (db:seed). |
4. Cursor & Claude Desktop Setup
Claude Desktop
Open claude_desktop_config.json:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
Add the server definition:
{
"mcpServers": {
"an5-orm": {
"command": "node",
"args": [
"/absolute/path/to/an5orm.an5-orm-vscode/dist/mcp/server.js"
],
"cwd": "/path/to/your/project",
"env": {
"DATABASE_URL": "sqlserver://localhost:1433;database=mydb;user=sa;password=secret"
}
}
}
}
Cursor IDE
- Open Settings → Features → MCP.
- Click + Add New MCP Server.
- Select Type:
command(stdio). - Paste the command and argument values obtained from AN5: Show MCP Server Configuration.
5. Security & Isolation Guarantees
- Path Traversal Protection: File operations in
an5_read_schema_fileverify that canonical paths remain strictly within the workspace boundary. Relative escapes (../) and external symlinks are rejected. - SQL Guardrails:
an5_query_databaseblocks schema-altering statements, chained semicolons, and write queries. - Protocol Separation: Standard output (
stdout) is strictly reserved for JSON-RPC MCP messages. Diagnostic outputs and warnings are redirected tostderr([an5-orm-mcp]) to prevent protocol corruption. - Mandatory Human Confirmation: Destructive operations cannot be executed autonomously by an AI agent; the parameter
confirm: truemust be explicitly approved.
6. Extension UI & Agent Skills Sync
Beyond the MCP server, the an5-orm-vscode extension provides dedicated developer tools in the Activity Bar:
Activity Bar Views
- Connections (
an5.connections): Securely manage database profiles. Test live connections, set active profile for tasks and debug terminals, or remove stale credentials. - Schema Explorer (
an5.schema): Inspect parsed.an5models, primary keys, fields, and relations directly in the sidebar tree. - Project Actions (
an5.actions): Fast one-click shortcuts foran5 generate,an5 push,an5 pull, and MCP installation.
Agent Skills Synchronization
Running AN5: Sync Agent Skills (an5.agentSkills.sync) automatically provisions repository agent context:
- Copies the managed ORM instructions template to
.agents/skills/an5-orm/SKILL.md. - Inspects
an5Orm.config.jsandpackage.jsonnpm scripts. - Updates the
<!-- AN5 agent context: start -->block inAGENTS.mdso coding assistants immediately recognize local project conventions without leaking credentials.
Application code from a user request
Call an5_generate_code with request and optional language. It returns schema, configured client location and generated API references for the calling AI model to write the requested snippet. It does not invoke a separate LLM or write application files. Choose the language explicitly in multilingual workspaces. The installed ORM must export prepareCodeRequest; older builds report an upgrade error.
Configure project paths and sign in to Google Sheets
The connection manager includes Project configuration for editing schema and client output paths without manually rewriting the ORM config. It preserves existing custom settings and writes a managed path block. Saving settings does not run generation or change the database.
Choose Sheets, then import a Google Desktop OAuth client JSON or enter the Client ID in Google OAuth application setup. Enable Sheets API and Drive API and configure consent/test users in your Google Cloud application. Click Sign in with Google and select a spreadsheet from the account. Tokens and OAuth client settings stay in VS Code SecretStorage, and the updated Sheets adapter refreshes access automatically.
The Google flow requests spreadsheet read/write access and Drive metadata to list files. It currently needs a local VS Code window: remote/Codespace extension hosts can continue using service accounts. A real OAuth client must be configured before testing with a Google account.