How do I use StatelyDB MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@StatelyDB MCP Server Validate this StatelyDB schema" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

StatelyDB MCP Server

Official

by StatelyCloud

Overview Schema Source Related Servers Discussions Admin

JavaScript

Local

StatelyDB MCP Server

A Model Context Protocol (MCP) server that integrates with the StatelyDB CLI to enable AI assistants to validate and manage StatelyDB schemas.

Prerequisites

Node.js: Version 20 or higher

Related MCP server: MCP Server Demo

Installation

Configuring for Claude Code

Run claude mcp add statelydb -- npx -y @stately-cloud/statelydb-mcp-server@latest to add the MCP server to your Claude Code.

Configuring with Claude Desktop

To use this MCP server with Claude Desktop, follow these steps:

Open your Claude Desktop App configuration file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Add the server configuration to the mcpServers section:

{
  "mcpServers": {
    "statelydb": {
      "command": "npx",
      "args": ["-y", "@stately-cloud/statelydb-mcp-server@latest"]
    }
  }
}

Save the file and restart Claude Desktop.

Manually install from npm registry

Install the server globally:

npm install -g @stately-cloud/statelydb-mcp-server

Alternatively, you can run it directly with npx:

npx @stately-cloud/statelydb-mcp-server@latest

From local source

To install directly from your local source code:

Clone or download this repository
Navigate to the project directory
Install dependencies and link the package locally:

# Install dependencies
npm install

# Build the TypeScript code
npm run build

# Create a global symlink to your local code
npm link

This will create a global statelydb-mcp-server command that uses your local code.

To unlink later, you can run:

npm unlink statelydb-mcp-server

Available Tools

This MCP server exposes the following tools:

1. `validate-schema`

Validates a StatelyDB elastic schema definition.

Input:

schema: String containing the schema definition

Output:

Success: "Schema is valid."
Failure: "Schema is invalid. Error: [error message]"

Example:

Could you validate this StatelyDB schema?

import {
  itemType,
  string,
  timestampSeconds,
  uint,
  uuid,
} from "@stately-cloud/schema";

/** A user of our fantastic new system. */
itemType("User", {
  keyPath: "/user-:id",
  fields: {
    id: {
      type: uuid,
      initialValue: "uuid",
    },
    displayName: {
      type: string,
    },
    email: {
      type: string,
    },
    lastLoginDate: {
      type: timestampSeconds,
    },
    numLogins: {
      type: uint,
    },
  },
});

2. `validate-migrations`

Validates that schema migrations are valid. This is the same as running stately schema put in dry-run mode.

Input:

schema: String containing the schema definition
schemaId: Your StatelyDB schema ID

Output:

Success: "Migrations are valid."
Failure: "Migrations are invalid. Error: [error message]"

Example:

Could you check if this StatelyDB schema has valid migrations?

import {
  itemType,
  string,
  timestampSeconds,
  uint,
  uuid,
} from "@stately-cloud/schema";

itemType("User", {
  keyPath: "/user-:id",
  fields: {
    id: {
      type: uuid,
      initialValue: "uuid",
    },
    displayName: {
      type: string,
    },
    email: {
      type: string,
    },
    lastLoginDate: {
      type: timestampSeconds,
    },
    loginCount: {
      type: uint,
    },
  },
});

migrate(1, "Rename the numLogins field", (m) => {
  m.changeType("User", (t) => {
    t.renameField("numLogins", "loginCount");
  });
});

3. `attempt-login`

Initiates the Stately login process, providing a URL for authentication.

Input:

None

Output:

URL for authentication: "Please visit this URL to complete the authentication process: [url]"

Example:

Could you help me log into StatelyDB?

4. `verify-login`

Verifies if the user is currently logged in to StatelyDB.

Input:

None

Output:

Success: "Login verified. [user information]"
Failure: "Not logged in."

Example:

Am I currently logged into StatelyDB?

5. `schema-put`

Publishes a schema to StatelyDB.

Input:

schema: String containing the schema definition
schemaId: Your StatelyDB schema ID

Output:

Success: "Schema published successfully: [output]"
Failure: "Failed to publish schema: [error message]"

Example:

Publish this StatelyDB schema:

import {
  itemType,
  string,
  timestampSeconds,
  uint,
  uuid,
} from "@stately-cloud/schema";

/** A user of our fantastic new system. */
itemType("User", {
  keyPath: "/user-:id",
  fields: {
    id: {
      type: uuid,
      initialValue: "uuid",
    },
    displayName: {
      type: string,
    },
    email: {
      type: string,
    },
    lastLoginDate: {
      type: timestampSeconds,
    },
    numLogins: {
      type: uint,
    },
  },
});

6. `schema-generate`

Generates client code for a specified language from a StatelyDB schema.

Input:

schemaId: Your StatelyDB schema ID
language: One of "typescript", "python", "ruby", "go"

Output:

List of generated files with their contents

Example:

Could you generate TypeScript client code for schema id 1234?

Security Considerations

This MCP server runs local commands on your machine. Always review schemas before publishing them.
The server requires access to the Stately CLI and your Stately authentication credentials.
No data is sent to external services except through the official Stately CLI.

License

Apache 2.0

Available Tools

6 tools

statelydb-attempt-loginB

Initiate StatelyDB login process and get an authorization URL

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

B3.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden, and it does disclose the single externally visible effect: it returns an authorization URL after starting a login process. It omits whether a server-side session or pending-auth state is created, how long the URL/state remains valid, and whether any credentials or config must already exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence that states the action and its result with no filler. It is close to minimal, though one clause on the follow-up verification step would have earned its space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple zero-parameter tool with no output schema, the description covers what the call does and what it produces, which is nearly enough. It stops short of the flow context an agent needs, namely that statelydb-verify-login must follow and that the returned URL is meant to be presented to the user.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes no parameters, so there is nothing for the description to disambiguate; the baseline for a zero-parameter tool applies. No misleading parameter information is present.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb ('Initiate') and resource ('StatelyDB login process') and states the immediate outcome ('authorization URL'), so an agent knows exactly what the call produces. It does not explicitly differentiate itself from the sibling statelydb-verify-login, which is the obvious next step in the same flow.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this versus statelydb-verify-login, no prerequisites, and no indication that this is the first step of a two-call login flow. The sequencing must be inferred entirely from the tool names.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

statelydb-schema-generateB

Generate client code from a published StatelyDB schema version definition. Supported languages: TypeScript, Python, Ruby, Go.

ParametersJSON Schema

Name	Required	Description	Default
`language`	Yes	The language to generate code for
`schemaId`	Yes	The schema ID

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden but delivers little: it does not say what is produced (files on disk, returned content, a URL), whether it is side-effect free, or whether authentication is required. Only the 'published' qualifier implies any constraint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, action front-loaded, no filler. The supported-languages clause is the only useful supplementary detail and is placed last where it belongs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a code-generation tool with no output schema and no annotations, the return shape matters a lot and is entirely unaddressed, leaving the agent unsure what it gets back. Parameters and source requirements are adequately covered, so it is minimally viable rather than deficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with both parameters documented, so the baseline is 3. The description's language list broadly mirrors the enum but adds no format, lookup, or value guidance beyond what the schema already supplies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (generate) and resource (client code from a published schema version definition), which clearly separates it from validate-schema and schema-put siblings. It stops short of explicitly naming those alternatives, but the action is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use guidance, no prerequisites, and no routing to alternatives such as statelydb-schema-put or the validate tools. The phrase 'published schema version' hints at a prerequisite but is never stated as one.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

statelydb-schema-putC

Publish an elastic schema version definition to StatelyDB

ParametersJSON Schema

Name	Required	Description	Default
`schema`	Yes	The schema definition to publish
`schemaId`	Yes	The schema ID

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. 'Publish' implies a persistent mutation, but the description does not disclose whether published versions are immutable, whether re-publishing the same schemaId is allowed, what permissions are required, or what happens on conflict.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler words. It is appropriately sized for the tool's surface, though its brevity is partly under-specification rather than discipline.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no annotations and no output schema, the description omits the workflow context an agent needs: preconditions (validation), the effect of publishing on existing versions, and the expected result. The safety and sequencing burden falls entirely on guesses.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are fully documented in the schema and the baseline is 3. The description adds nothing beyond the schema — it does not clarify the expected format of 'schema' (elastic schema DSL?) or the ID conventions for 'schemaId'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Publish') and resource ('elastic schema version definition to StatelyDB'), so the action is unambiguous. It does not explicitly differentiate itself from sibling verbs like statelydb-validate-schema or statelydb-schema-generate, though the verb choice implicitly separates it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to publish versus validate or generate, and no prerequisite stated (e.g., whether the schema must first pass statelydb-validate-schema or statelydb-validate-migrations). The agent must infer the workflow from sibling names alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

statelydb-validate-migrationsC

Validate schema migrations inside of a StatelyDB elastic schema definition.

ParametersJSON Schema

Name	Required	Description	Default
`schema`	Yes	The schema definition to validate
`schemaId`	Yes	The schema ID

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It doesn't disclose whether validation is read-only, what it returns, whether it fails fast, or what conditions cause failure — only that some validation happens.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single efficient sentence with the verb and scope front-loaded. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a validation tool with no annotations and no output schema, the description should explain what a successful or failed validation yields. Instead it stops at the purpose, leaving an agent without enough to interpret results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are documented in the schema. The description adds no syntax or format detail beyond restating that the schema is validated, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb (validate) and resource (schema migrations inside a StatelyDB elastic schema definition), distinguishing it from the sibling statelydb-validate-schema via the 'migrations' scope. It does not explicitly name the sibling or explain the boundary, but the resource is specific enough.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use or when-not-to-use guidance is present. It does not say how it differs from statelydb-validate-schema or when a caller should prefer this tool, leaving the agent to infer from names alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

statelydb-validate-schemaC

Validate a StatelyDB elastic schema definition.

ParametersJSON Schema

Name	Required	Description	Default
`schema`	Yes	The schema definition to validate

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full behavioral burden. 'Validate' implies a read-only check, but the description never states whether it mutates state, requires auth, what happens on invalid input, or what the result looks like. This is a thin disclosure for a tool with zero annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One short declarative sentence with the verb and resource front-loaded and zero filler. It is efficient, though its brevity comes at the cost of the missing usage and behavioral detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter tool this is minimally adequate, but with no output schema and no annotations the description should at least explain what a validation result conveys (success/failure, error reporting). That gap leaves the agent unable to predict the response.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single 'schema' parameter is fully documented in the schema (100% coverage) as 'The schema definition to validate,' so the baseline of 3 applies. The description adds no additional meaning such as format expectations or size limits beyond what the schema already conveys.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Validate') and resource ('StatelyDB elastic schema definition'), so the action and object are unambiguous. It does not, however, distinguish itself from siblings like statelydb-validate-migrations or statelydb-schema-put, leaving the agent to infer scope from names alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no when-to-use guidance, no prerequisites (e.g., must a schema be generated first), and no reference to alternatives such as validate-migrations or schema-put. The agent must infer context purely from the tool name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

statelydb-verify-loginA

Verify if the user is logged in to StatelyDB. This command can also tell you what organizations, stores, and schemas you have access to.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full behavioral burden. It usefully discloses the return content (organizations, stores, schemas), but it does not state whether the operation is read-only, requires authentication, has side effects, or what happens if the user is not logged in.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two tightly written sentences with no wasted words. The core verification purpose is front-loaded, and the secondary return-value note follows efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter tool with no output schema, the description covers the primary purpose and the main return content. It omits error behavior and usage context relative to similar tools, but given the low complexity, it is largely complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline is 4. The description does not need to explain parameter semantics, and the input schema is trivially complete with no properties.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Verify if the user is logged in to StatelyDB.' It also adds that the command reveals accessible organizations, stores, and schemas, which clarifies its scope. However, it does not explicitly distinguish itself from the sibling tool statelydb-attempt-login, so it falls short of full sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. An agent could reasonably confuse it with statelydb-attempt-login, and nothing here resolves that ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

6 tool updatesv1.0.0Sep 13, 2026
- First observedstatelydb-attempt-login
- First observedstatelydb-schema-generate
- First observedstatelydb-schema-put
- First observedstatelydb-validate-migrations
- First observedstatelydb-validate-schema
- First observedstatelydb-verify-login

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.3/5.0

Scored 2026-09-13 09:11 across 6 tools

Disambiguation4/5

Each tool targets a distinct action: validating schemas vs migrations, initiating vs verifying login, publishing, and code generation. The two validate tools could be momentarily confused, but their descriptions clearly differentiate schema-level from migration-level validation.

Naming Consistency4/5

All tools share the 'statelydb-' prefix and use hyphenated lowercase, which is readable. Minor deviation: validate/attempt/verify tools use verb_noun ordering while schema-put and schema-generate use noun_verb ordering.

Tool Count5/5

Six tools is well-scoped for a schema validation, publishing, and code-generation workflow. Each tool earns its place with no redundancy.

Completeness3/5

The core validate → publish → generate workflow is covered, plus login handling. However, there is no dedicated tool to read/get or delete an existing schema version, and listing access depends on verify-login, leaving notable gaps for full lifecycle management.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

hithereiamaliff-mcp-nextcloudOAuth
ai.smithery
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Cloud Storage File Systems Workplace & Productivity
238
mcp COAuth
com.wix
A Model Context Protocol server for Wix AI tools
Developer Tools Content Management Systems App Automation
216
ChrysaiOAuth
com.chrysai.www
Hosted MCP server for AI-driven data ops. Create apps, manage schemas, and CRUD structured data.
Data Platforms Developer Tools App Automation
2
OneSchema MCP Server
co.oneschema
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Data Platforms App Automation
1

Related MCP Servers

TianGong-AI-MCP
Autonomous Agents Code Execution Developer Tools
linancn
A
license
Not graded
quality
D
maintenance
A Model Context Protocol (MCP) server that supports STDIO, SSE and Streamable HTTP protocols for AI model interactions.
Updated a year ago (2025-09-25 15:10 UTC)
5 npm
1
MIT
MCP Server Demo
Drakoxw
F
license
B
quality
D
maintenance
A Model Context Protocol server implementation that can be run directly or through Docker, enabling AI assistants to interact with external systems through the MCP standard.
Updated a year ago (2025-07-14 04:38 UTC)
2
-
@pilat/mcp-datalink
Databases Developer Tools
pilat
A
license
Not graded
quality
C
maintenance
MCP server for PostgreSQL, MySQL, and SQLite that gives AI assistants secure database access via the Model Context Protocol.
Updated a day ago (2026-09-16 09:08 UTC)
25 npm
4
MIT
Semantic BI MCP
Databases AI & Machine Learning
LovroBubanic
F
license
Not graded
quality
D
maintenance
Model Context Protocol (MCP) server that gives AI assistants a safe, correct data-analyst capability over business metrics - without raw SQL improvisation.
Updated 3 months ago (2026-06-06 12:59 UTC)
-

StatelyDB MCP Server

Prerequisites

Installation

Configuring for Claude Code

Configuring with Claude Desktop

Manually install from npm registry

From local source

Available Tools

1. validate-schema

2. validate-migrations

3. attempt-login

4. verify-login

5. schema-put

6. schema-generate

Security Considerations

License

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

1. `validate-schema`

2. `validate-migrations`

3. `attempt-login`

4. `verify-login`

5. `schema-put`

6. `schema-generate`