Repository avatar
Databases
v1.0.0
active

synapcores

io.github.SynapCores/synapcores

AI-native database: SQL, vector search, Cypher graph, AutoML and LLM tools over MCP.

Documentation

SynapCores MCP Server

SynapCores is an AI-native database: SQL, vector search, a Cypher graph, in-database AutoML and LLM generation in one self-hosted engine. The engine has a built-in Model Context Protocol server at /v1/mcp, so an AI assistant can query and build on your data directly.

This package, @synapcores/mcp, is the stdio connector for that server. It is small, MIT-licensed and has zero dependencies (Node.js 18+).

MCP client  ⇄  stdio  ⇄  @synapcores/mcp  ⇄  HTTP (JSON-RPC)  ⇄  SynapCores /v1/mcp

Tools

The engine provides 15 tools:

ToolWhat it does
list_tablesList the tables in the database
describe_tableColumns, types and constraints for a table
queryRun a SELECT and return rows
executeRun INSERT / UPDATE / DELETE and DDL (CREATE / ALTER / DROP)
validate_queryCheck SQL syntax, optionally with the execution plan
sql_manualSynapCores SQL syntax and examples
semantic_searchSimilarity search over a vector collection; the query text is embedded for you
embed_textVector embedding for any text
graph_queryCypher on the graph (MATCH / MERGE / CREATE / SET / DELETE, gds algorithms)
train_modelTrain an AutoML model on a table column
predictScore rows with a trained model
list_modelsList trained models
describe_modelAlgorithm, metrics and feature importance of a model
generate_textGenerate text with the engine's configured LLM
agent_soulInspect the database's learned runs, episodes, goals and plans (administrator key)

The tools come from the engine, so they update when you upgrade SynapCores. If the engine isn't reachable, the server still starts and lists these 15 tools from a bundled copy (taken from SynapCores 2.4.8); tool calls then return an error asking you to start the engine.

1. Run SynapCores

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

See synapcores.com/download for other options. The gateway listens on http://127.0.0.1:8080 by default.

2. Get an API key

Use an API key, not a login token: API keys don't expire after 24 hours. The installer prints one at first boot. To create a dedicated key:

TOKEN=$(curl -s http://127.0.0.1:8080/v1/auth/login -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"<your admin password>"}' | jq -r .access_token)

curl -s http://127.0.0.1:8080/v1/api-keys -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"claude-code","permission":"FullAccess"}' | jq -r .raw_key

The key is shown once. Keep it in an environment variable:

export SYNAPCORES_API_KEY=<the key>

Read-only keys: create the key with "permission":"ReadOnly" to let the assistant read and search while the engine refuses SQL writes and DDL through execute, and Cypher writes through graph_query.

3. Add SynapCores to Claude Code

stdio, with this package

claude mcp add synapcores \
  -e SYNAPCORES_URL=http://127.0.0.1:8080 \
  -e SYNAPCORES_API_KEY=$SYNAPCORES_API_KEY \
  -- npx -y @synapcores/mcp

HTTP, no package

Claude Code can also talk to the engine's MCP endpoint directly:

claude mcp add --transport http synapcores http://127.0.0.1:8080/v1/mcp \
  --header "Authorization: Bearer $SYNAPCORES_API_KEY"

For a team repo, add --scope project and single-quote the header ('Authorization: Bearer ${SYNAPCORES_API_KEY}') so .mcp.json stores the variable name, not the key.

Check the connection with claude mcp list, then ask:

"What tables are in my SynapCores database? Describe the biggest one."

"Find the five support articles most similar to 'reset my password'."

"Train a model on customers to predict churned, then show the 10 highest-risk customers."

Configuration

VariableDescription
SYNAPCORES_URLGateway URL. Default http://127.0.0.1:8080.
SYNAPCORES_API_KEYSynapCores API key, sent as Authorization: Bearer.
SYNAPCORES_TIMEOUT_MSPer-request timeout. Default 300000 (5 minutes).

Every tool call goes through the gateway's authentication, so the assistant sees exactly what its API key is allowed to see.

stdout carries only JSON-RPC messages; diagnostics go to stderr.

Development

npm test                                   # unit tests (no engine needed)
SYNAPCORES_API_KEY=... npm run smoke       # live check against a running engine

Links

License

MIT © SynapCores

NPM
@synapcores/mcp
Install Command
npm install @synapcores/mcp