I contribute to Simfinity.js. Its optional @simtlix/simfinity-mcp package can generate tools from a GraphQL schema. It works independently of the PostgreSQL and MongoDB adapters, so this example starts with an ordinary GraphQL schema and a small in-memory catalog.

We'll inspect the generated tool, call it directly, and then expose the same operation over stdio. No database or model API key is needed for this example.

The complete example is available as a Gist. Download its ZIP if you prefer to start with the files already in place.

Start with a schema you can inspect

In an empty directory, run:

npm init -y
npm pkg set type=module
npm install @simtlix/simfinity-mcp@3.2.0 graphql@^16.11.0

Create schema.js:

import {
  GraphQLID,
  GraphQLList,
  GraphQLNonNull,
  GraphQLObjectType,
  GraphQLSchema,
  GraphQLString,
} from 'graphql';

const starters = [
  { id: 'pg', name: 'PostgreSQL starter', database: 'postgresql' },
  { id: 'mongo', name: 'MongoDB starter', database: 'mongodb' },
];

const Starter = new GraphQLObjectType({
  name: 'Starter',
  fields: {
    id: { type: new GraphQLNonNull(GraphQLID) },
    name: { type: new GraphQLNonNull(GraphQLString) },
    database: { type: new GraphQLNonNull(GraphQLString) },
  },
});

export const schema = new GraphQLSchema({
  query: new GraphQLObjectType({
    name: 'Query',
    fields: {
      starters: {
        type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(Starter))),
        description: 'Find the demo starter projects by database.',
        args: { database: { type: GraphQLString } },
        resolve: (_source, { database }) => starters.filter(
          (starter) => !database || starter.database === database,
        ),
      },
      serviceStatus: {
        type: GraphQLString,
        resolve: () => 'demo',
      },
    },
  }),
});

The data is a two-row demo catalog. The starters resolver accepts a database name and returns matching rows. A second root field, serviceStatus, will let us check that the MCP configuration exposes only the operation we choose.

In an application, the resolver could use your existing data access code. With a Simfinity-generated schema, pass the built schema once type registration and database initialization have completed.

Choose the operation and result fields

Create options.js:

export const options = {
  include: ['starters'],
  toolNamePrefix: 'catalog_',
  toolOverrides: {
    starters: {
      description: 'Find the demo starter projects by database.',
      selection: 'id name database',
    },
  },
  limits: { maxResultBytes: 8192 },
};

include contains the GraphQL root field name. The prefix changes the name presented to MCP clients to catalog_starters; the underlying GraphQL field remains starters.

The explicit selection fixes the result fields to id, name, and database. Clients supply arguments for that operation. They do not supply an arbitrary GraphQL selection through this tool.

This selection also means the generator omits its automatic outputSchema for the tool. Successful calls still provide structuredContent, which we'll use below.

The 8 KB limit caps the logical result payload. It is useful when choosing how much data to return, but it is not a database execution limit and cannot undo a mutation that already ran.

Inspect and call the generated tool

Create inspect.js:

import { generateMCPTools } from '@simtlix/simfinity-mcp';
import { schema } from './schema.js';
import { options } from './options.js';

const { tools, callTool, getOperation } = generateMCPTools(schema, options);

console.log('Tools:', tools.map((tool) => tool.name));
console.log('Input schema:', JSON.stringify(tools[0].inputSchema, null, 2));
console.log('GraphQL operation:', getOperation('catalog_starters'));

const result = await callTool('catalog_starters', { database: 'postgresql' });
if (result.isError) throw new Error(JSON.stringify(result.content));
console.log('Result:', JSON.stringify(result.structuredContent, null, 2));

Run it:

node inspect.js

The tool list contains one entry:

Tools: [ 'catalog_starters' ]

serviceStatus is absent. The generated input schema has an optional, nullable string named database, matching the GraphQL argument. The generated operation is:

query startersOperation($database: String) {
  starters(database: $database) { id name database }
}

Calling the tool with database: 'postgresql' returns:

{
  "starters": [
    {
      "id": "pg",
      "name": "PostgreSQL starter",
      "database": "postgresql"
    }
  ]
}

This is a useful place to check the mapping before involving a client. You can see the published name, generated input contract, GraphQL document, and actual result together.

The direct call does not require the MCP SDK. Install the SDK when you're ready to use a protocol transport.

Serve the same tool over stdio

Install the optional transport dependency:

npm install "@modelcontextprotocol/sdk@^1.13.0"

Create stdio.js:

import { startStdioMCPServer } from '@simtlix/simfinity-mcp';
import { schema } from './schema.js';
import { options } from './options.js';

await startStdioMCPServer(schema, {
  ...options,
  serverName: 'starter-catalog',
  serverVersion: '1.0.0',
});

Configure your MCP client's local server command to launch node with the absolute path to stdio.js. For example, the command's argument would be /path/to/mcp-example/stdio.js on a POSIX system or C:\path\to\mcp-example\stdio.js on Windows.

The relative imports resolve from the entry-point file, so the client does not need to start in the example directory. Use the full path to your Node executable if the client cannot find it through its environment.

Keep application logs off stdout in this entry point, because stdout carries MCP protocol messages. Use console.error for diagnostics. The separate inspect.js script can print normally because it is not a protocol server.

The client should discover catalog_starters and be able to call it with:

{ "database": "postgresql" }

Bring application rules with the schema

This demo reads an in-memory array and has no user accounts. Before replacing it with application data, decide which identity reaches the resolvers and how that identity is verified.

The operation allowlist controls which tools are published. Authorization still belongs in the application. For standalone Simfinity MCP execution, the schemaPlugins option can install schema hooks such as the auth plugin; creating a plugin object alone does not apply it. The application must supply trusted context. Tool arguments should never be treated as proof of the caller's identity.

If you add mutations later, account for the same transaction requirements as the GraphQL API. Cancellation does not roll back database work that has already started. For an HTTP transport, follow the documented authentication and host/origin configuration rather than deploying this local stdio example as a public endpoint.

I checked this example with the published @simtlix/simfinity-mcp 3.2.0 package on Node.js 24.15.0. The checks covered direct execution, filtering, a nullable argument, rejection of an invalid argument type, and discovery and invocation through an actual MCP stdio client. The exposed tool list contained only catalog_starters.

The MCP guide covers the database-backed setup and HTTP transport. The MCP reference documents the remaining generation and execution options. For a complete API with storage, start with the PostgreSQL or MongoDB quick start.

Simfinity.js generates those recurring pieces from GraphQL object types. Version 3.2.0 provides MongoDB/Mongoose and PostgreSQL adapters, plus an optional package for exposing GraphQL operations as MCP tools. The project is open source under Apache-2.0.

This walkthrough uses the published PostgreSQL starter. It includes a nested series/season example, so there is a relationship to inspect as well as a working API.

Start with the domain

The type definition uses the standard graphql package. A minimal entity looks like this:

import {
  GraphQLID,
  GraphQLNonNull,
  GraphQLObjectType,
  GraphQLString,
} from 'graphql';

const SerieType = new GraphQLObjectType({
  name: 'Serie',
  fields: {
    id: { type: GraphQLID },
    name: { type: new GraphQLNonNull(GraphQLString) },
  },
});

Register the type with the PostgreSQL runtime, supplying the singular and plural operation names:

import pg from 'pg';
import { createPostgres } from '@simtlix/simfinity-postgres';

const pool = new pg.Pool({
  connectionString: process.env.DATABASE_URL,
});
const simfinity = createPostgres({ pool, schema: 'series_api' });

simfinity.connect(null, SerieType, 'serie', 'series');
const schema = simfinity.createSchema();
await simfinity.initializeDatabase({ mode: 'create' });

The resulting schema can be served through GraphQL Yoga. The downloaded starter includes that server setup, shutdown handling, a Season type and a controller. The snippets above show the core registration flow; the starter is the complete application.

Run the released starter

Use Node.js 22+ for the starter and PostgreSQL 15+. Download and extract the v3.2.0 starter archive, then enter its postgres directory:

cd simfinity-3.2.0-starters/postgres
npm install

For a disposable local database, run:

docker run --name simfinity-postgres-demo -e POSTGRES_PASSWORD=simfinity -e POSTGRES_DB=series -p 127.0.0.1:5432:5432 -d postgres:18-alpine

In a POSIX shell, set the connection string and start the app:

export DATABASE_URL='postgresql://postgres:simfinity@127.0.0.1:5432/series'
npm start

In PowerShell, use $env:DATABASE_URL = 'postgresql://postgres:simfinity@127.0.0.1:5432/series' before npm start. If port 5432 is occupied, choose another host port and update the connection string. These credentials are for the disposable local example.

Open http://127.0.0.1:4000/graphql. Create a serie and its first season together:

mutation {
  addserie(input: {
    name: "The Expanse"
    seasons: { added: [{ number: 1 }] }
  }) {
    id
    name
    createdBy
    seasons { id number }
  }
}

Then read it back:

query {
  series {
    name
    seasons { number }
  }
}

The generated relationship resolves the season from its parent. PostgreSQL also has a real foreign key from the season's serie column to the serie table. The API relationship and the database constraint come from the relationship metadata in the type definitions.

Add application rules where they belong

Generated CRUD is the starting point. Controllers and lifecycle hooks let you add domain behavior; validators, query scopes, state transitions and authorization rules provide other extension points.

Authentication remains application-owned. Configure the authorization policy and trusted request context for your deployment. The starter's fixed quickstart-user context is demonstration code, not a login system.

Storage initialization is explicit. create mode creates missing generated objects and checks existing definitions; validate mode checks the schema without DDL. Schema evolution still needs deliberate migrations.

Expose selected operations to an MCP client

The optional @simtlix/simfinity-mcp package works with either database adapter. Once the application has initialized its GraphQL schema, tool definitions can be generated from selected operations:

import { generateMCPTools } from '@simtlix/simfinity-mcp';

const { tools } = generateMCPTools(schema, {
  include: ['series'],
  limits: {
    maxPageSize: 100,
    defaultPagination: { page: 1, size: 20 },
  },
});

console.log(tools.map((tool) => tool.name));

Install that package separately when needed. Tool generation needs GraphQL; server/transport factories also use the optional MCP SDK. The MCP guide covers transports, trusted context and authorization.

Choosing a backend

Choose the adapter during application startup. PostgreSQL uses UUID identities, SQL constraints and its own native Model/Session APIs. MongoDB uses Mongoose, and generated mutations require a replica set or sharded cluster. Selecting an adapter does not migrate an existing database or translate arbitrary Mongoose calls into SQL.

Start with the PostgreSQL quick start, review the compatibility boundaries, or explore the larger Series Sample Project.

Source code and issues

The downloaded PostgreSQL starter was exercised locally with a nested create, query readback and database foreign-key inspection.