coremcp

CoreMCP

A Model Context Protocol (MCP) server, written in Go, that exposes SQL databases as MCP tools and prompts. It runs as a single static binary, embeds its drivers, and talks either stdio (for local MCP clients like Claude Desktop) or an outbound WebSocket (for remote operation behind NAT).

Currently ships with an MSSQL adapter (SQL Server 2000+, Turkish_CI_AS collation aware). Firebird is in progress; PostgreSQL and MySQL are on the roadmap.

Status

• Stable: MSSQL adapter, stdio transport, schema discovery, custom tools, NOLOCK / Turkish normalization middleware, WebSocket connect mode.
• In progress: Firebird adapter (factory currently returns a placeholder error).
• Roadmap: PostgreSQL, MySQL, HTTP transport, audit log, query result cache.

Defaults

CoreMCP is read-only by default. Omitting readonly in a source config leaves SELECT-only mode active; you have to set readonly: false to enable execute_procedure. Even so, the recommended posture is a dedicated DB user with SELECT (and EXECUTE only on the procedures you intend to expose) — defense in depth rather than relying solely on the server-side guard.

Install

Binary

Download from the Releases page — linux/amd64, linux/arm64, darwin/{amd64,arm64}, windows/amd64.

One-line installer (Linux/macOS):

curl -fsSL https://get.corebasehq.com | sh

Docker

docker pull y11t0/coremcp:latest

Multi-arch image (linux/amd64, linux/arm64).

From source

Requires Go 1.23+.

git clone https://github.com/corebasehq/coremcp.git
cd coremcp
go build -o coremcp ./cmd/coremcp

Configuration

coremcp.yaml in the working directory:

server:
  name: "coremcp-agent"
  version: "0.1.0"
  transport: "stdio"
  port: 8080

logging:
  level: "info"
  format: "json"

sources:
  - name: "my_database"
    type: "mssql"
    dsn: "sqlserver://username:password@localhost:1433?database=mydb&encrypt=disable"
    readonly: true
    no_lock: true            # READ UNCOMMITTED isolation (WITH (NOLOCK) equivalent)
    normalize_turkish: true  # Turkish character + mojibake normalization

See coremcp.example.yaml for a fuller example.

DSN format

MSSQL:

sqlserver://username:password@host:port?database=dbname&encrypt=disable

Dummy adapter (for testing without a real DB):

dummy://test

Source options

Option	Type	Default	Description
name	string	—	Unique source identifier
type	string	—	Adapter type: mssql, dummy
dsn	string	—	Connection string
readonly	bool	true	SELECT-only at the config level. Set false explicitly to allow execute_procedure.
no_lock	bool	false	(MSSQL only) Run SELECTs under READ UNCOMMITTED. Equivalent to WITH (NOLOCK) on every table reference. Eliminates shared lock acquisition on busy OLTP. Trade-off: dirty reads possible.
normalize_turkish	bool	false	(MSSQL only) Two-way middleware. Outgoing: Turkish characters inside SQL string literals are folded to ASCII uppercase before the query is sent ('Hüseyin' → 'HUSEYIN'). Incoming: Windows-1254 / Windows-1252 mojibake in result strings is auto-corrected. Intended for legacy Turkish ERP databases on Turkish_CI_AS.

Example: MSSQL with NOLOCK

sources:
  - name: "oltp_db"
    type: "mssql"
    dsn: "sqlserver://user:pass@localhost:1433?database=production&encrypt=disable"
    readonly: true
    no_lock: true

Example: legacy Turkish ERP

sources:
  - name: "erp_db"
    type: "mssql"
    dsn: "sqlserver://user:pass@localhost:1433?database=LOGO&encrypt=disable"
    readonly: true
    no_lock: true
    normalize_turkish: true

How the Turkish middleware behaves:

Model emits	Sent to DB	Why
WHERE ADI = 'Hüseyin'	WHERE ADI = 'HUSEYIN'	ERP stores names as uppercase ASCII
WHERE SEHIR LIKE '%şeker%'	WHERE SEHIR LIKE '%SEKER%'	Ş → S
WHERE SEHIR = 'İstanbul'	WHERE SEHIR = 'ISTANBUL'	İ → I

Mojibake correction on inbound rows:

DB returns	Fixed	Cause
GÐKHAN	GĞKHAN	Win-1254 byte 0xD0 read as Win-1252
ÝSTANBUL	İSTANBUL	Win-1254 byte 0xDD read as Win-1252
ÞEHİR	ŞEHİR	Win-1254 byte 0xDE read as Win-1252

Security configuration

security:
  max_row_limit: 1000        # forced LIMIT cap
  enable_pii_masking: true
  pii_patterns:
    - name: "credit_card"
      pattern: '\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b'
      replacement: "****-****-****-****"
      enabled: true
    - name: "email"
      pattern: '\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b'
      replacement: "***@***.***"
      enabled: true
    - name: "turkish_id"
      pattern: '\b[1-9]\d{10}\b'
      replacement: "***********"
      enabled: true

What this enables:

• AST-based query validation. SQL is parsed; DROP, ALTER, UPDATE, DELETE, TRUNCATE, EXEC, etc. are rejected before reaching the DB. Treat as one layer, not the only layer — pair with a least-privilege DB role.
• Forced row cap. LIMIT is appended (or wrapped) on every SELECT so a model never streams millions of rows back through the protocol.
• PII masking. Regex-based post-processing on result strings before they reach the client.

Usage

CoreMCP has two operation modes.

1. Local (serve)

For local MCP clients (Claude Desktop, etc.):

coremcp serve --config coremcp.yaml

stdio is the default transport:

coremcp serve -t stdio

Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "coremcp": {
      "command": "/path/to/coremcp",
      "args": ["serve", "-c", "/path/to/coremcp.yaml"],
      "env": {}
    }
  }
}

2. Remote (connect)

connect opens an outbound WebSocket to a relay (typically CoreBase Cloud) and serves MCP traffic over it. The agent never accepts inbound connections, so it works from inside networks that don't allow inbound 443 (factory floors, corporate VPCs, hospital networks).

coremcp connect --server="wss://api.corebasehq.com/ws/agent" --token="sk_xxx"

Flags:

-s, --server string              Relay WebSocket URL (required)
-t, --token string               Authentication token (required)
-a, --agent-id string            Agent ID (auto-generated if omitted)
-r, --max-reconnect int          Max reconnect attempts (default 10; 0 = infinite)
-d, --reconnect-delay duration   Delay between reconnect attempts (default 5s)

Example, long-running:

./coremcp connect \
  --server="wss://api.corebasehq.com/ws/agent" \
  --token="sk_xxx" \
  --agent-id="site-istanbul-001" \
  --max-reconnect=0

Wire commands supported by the relay protocol:

• run_sql — execute SQL
• get_schema — dump cached schema
• list_sources — enumerate configured sources
• health_check — agent liveness
• config_sync — push updated source configs to the running agent

Architecture

coremcp/
├── cmd/coremcp/       # CLI entry point
│   ├── main.go
│   ├── root.go
│   ├── serve.go       # stdio mode
│   └── connect.go     # WebSocket mode
├── pkg/
│   ├── adapter/       # Database adapters
│   │   ├── factory.go
│   │   ├── dummy/
│   │   └── mssql/
│   ├── config/
│   ├── core/          # Shared types, Source interface
│   ├── security/      # Query validation, PII masking
│   └── server/        # MCP server
└── coremcp.yaml

Tools and prompts

Built-in tools

query_database

Arbitrary SQL against a configured source.

• source_name (required)
• query (required)

list_tables

Tables with column counts, primary keys, foreign key counts.

• source_name (required)

describe_table

Full schema for one table: columns, types, nullability, PKs, FKs, column comments.

• source_name (required)
• table_name (required)

list_views

All views with column definitions.

• source_name (required)

list_procedures

Stored procedures with parameter names, types, modes (IN/OUT/INOUT), and a ready-to-copy example call.

• source_name (required)

execute_procedure

Calls a stored procedure with named parameters. Only enabled when readonly: false.

• source_name (required)
• procedure_name (required)
• params (optional) — JSON object of name/value pairs

Hardening:

• Procedure name validated against ^[a-zA-Z_][a-zA-Z0-9_#@.]*$
• Parameter names validated (alphanumeric + underscore)
• Values bound via sql.Named — no string interpolation
• Rejected outright when source is readonly: true

Example:

{
  "source_name": "erp_db",
  "procedure_name": "sp_CiroHesapla",
  "params": "{\"StartDate\":\"2024-01-01\",\"EndDate\":\"2024-12-31\"}"
}

Custom tools

Define reusable parameterized queries as first-class MCP tools:

custom_tools:
  - name: "get_daily_sales"
    description: "Daily sales summary for a given date"
    source: "production_db"
    query: "SELECT * FROM orders WHERE DATE(created_at) = '{{date}}'"
    parameters:
      - name: "date"
        description: "Date in YYYY-MM-DD format"
        required: true

  - name: "get_top_customers"
    description: "Top N customers by order count"
    source: "production_db"
    query: "SELECT user_id, COUNT(*) AS order_count FROM orders GROUP BY user_id ORDER BY order_count DESC LIMIT {{limit}}"
    parameters:
      - name: "limit"
        description: "Number of customers to return"
        required: true
        default: "10"

These get exposed to the model with their declared parameter schema, so the model can call them directly rather than re-deriving the SQL each turn.

database_schema prompt

On startup CoreMCP connects to every configured source, scans tables / columns / keys / relationships, and extracts column comments (e.g. MS_Description on MSSQL). The result is exposed as a single MCP prompt that primes the model with schema context — including the comments — so it can write correct queries without manual schema dumps in every conversation.

Adding adapters

1. Create pkg/adapter/yourdb/.
2. Implement core.Source.
3. Register in pkg/adapter/factory.go.

pkg/adapter/dummy/dummy.go is the minimum reference implementation.

Roadmap

• Schema discovery on startup
• Column comments / descriptions
• Built-in list_tables / describe_table
• Custom parameterized tools
• AST-based query sanitization
• PII masking
• Forced row cap
• WebSocket connect mode
• Auto-reconnect
• Remote config sync
• NOLOCK / READ UNCOMMITTED per source (MSSQL)
• Turkish character + mojibake middleware (MSSQL)
• View and procedure discovery (list_views, list_procedures, execute_procedure)
• Firebird adapter (in progress)
• PostgreSQL adapter
• MySQL adapter
• HTTP transport
• Query result cache
• Write operations (with explicit safety guards)
• Audit logging
• Multi-agent management
• Real-time monitoring

Contributing

See CONTRIBUTING.md. Security reports: SECURITY.md.

License

Apache License 2.0 — see LICENSE.

Support

• Report a bug
• Request a feature
• Email: support@corebasehq.com

---

About

CoreMCP is the on-prem agent component of CoreBase — memory infrastructure for the AI agents your customers use. CoreBase gives those agents structured access to operational systems (SQL Server 2000+, REST, GraphQL, Slack, Microsoft 365) and layers Corporate Memory on top: the schema relationships, terminology, and proven query patterns that turn raw access into accurate answers.