Fluent MCP Server

An MCP server that brings ServiceNow Fluent SDK capabilities to AI-assisted development environments. Enables natural language interaction with ServiceNow SDK commands, API specifications, code snippets, and development resources.

Built for @servicenow/sdk 4.8.1.

Key Features

• Complete SDK Coverage - ServiceNow SDK commands: init, build, install, dependencies, transform, download, clean, pack, explain, query

• Rich Resources - API specifications, instructions, and code snippets for 64 ServiceNow metadata types

• API Documentation Lookup - explain_fluent_api returns SDK docs for any Fluent API or guide — no project required

• Auto-Authentication - Automatic auth profile detection and session management via environment variables

• Session-Aware - Maintains working directory and auth context across commands

This MCP server implements the Model Context Protocol specification with the following capabilities:

Core

• Resources - 300+ resources across 64 ServiceNow metadata types (API specs, instructions, snippets, prompts)

• Tools - 11 ServiceNow SDK commands plus resource-lookup tools, with full parameter validation. Read tools (get-api-spec, get-snippet, get-instruct, check_auth_status) declare an outputSchema and return structuredContent for programmatic consumers

• Prompts - Development workflow templates for common ServiceNow tasks (coding_in_fluent, create_custom_ui)

• Logging & Progress - Structured logging for debugging and monitoring; progress notifications for long-running commands (build, install, transform, download) when the client supplies a progress token

Client Capabilities (used by this server)

The server leverages these MCP client capabilities when available:

• Roots - Requests workspace roots from the client for context-aware operations

  • Falls back to project root when client doesn't provide roots

• Elicitation - Interactive parameter collection for complex workflows

  • init_fluent_app - Prompts for missing project parameters (workingDirectory, template, appName, etc.)

  • Supports both creation and conversion workflows with smart validation

  • Handles user acceptance/rejection of elicited data

• Session Management - Tracks working directory per session for multi-project workflows

• Root Fallback - Automatically falls back to MCP root context when no session directory is set

• Error Handling - Comprehensive error messages with actionable guidance

• Type Safety - Full TypeScript implementation with strict typing

Related MCP server: servicenow-mcp-server

Quick Start

# Test with MCP Inspector
npx @modelcontextprotocol/inspector npx @modesty/fluent-mcp

# Or use in your MCP client (see Configuration below)

Example prompt:

Create a new Fluent app in ~/projects/time-off-tracker to manage employee PTO requests

Available Tools

SDK Commands

Note: Authentication is automatically configured at startup via environment variables. The auth parameter is auto-injected from the session for commands that require instance access. Use init_fluent_app to establish working directory context for subsequent commands.

Looking up Fluent APIs with explain_fluent_api

explain_fluent_api wraps now-sdk explain and returns SDK documentation for any Fluent API class or topic guide. It works from any directory — no Fluent project required.

topic matches an API name (e.g. BusinessRule, Acl), a guide name (e.g. business-rule-guide, atf-guide), or a tag keyword (e.g. flow, atf, email). The SDK resolves by exact name first, then by tag.

Resources

Standardized URI patterns following MCP specification:

Supported Metadata Types

64 metadata types across the following categories:

Core Types: acl, application-menu, business-rule, client-script, cross-scope-privilege, data-policy, form, import-set, instance-scan, list, property, role, scheduled-script, script-action, script-include, scripted-rest, sla, table, ui-action, ui-page, ui-policy, user-preference

Table Types: column, column-generic

Service Catalog: catalog-item, catalog-item-record-producer, catalog-ui-policy, catalog-client-script, catalog-variable, variable-set

Email: email-notification, inbound-email-action

Automation & Workflow: flow, custom-action, playbook

Integration & Connections: alias, alias-template, retry-policy, rest-message, data-lookup

AI & Now Assist: ai-agent, ai-agent-workflow, now-assist-skill-config

Service Portal: service-portal, sp-header-footer, sp-page-route-map

Workspace & Analytics: workspace, dashboard

ATF (Automated Test Framework): atf-appnav, atf-catalog-action, atf-catalog-validation, atf-catalog-variable, atf-email, atf-form, atf-form-action, atf-form-declarative-action, atf-form-field, atf-form-sp, atf-reporting, atf-rest-api, atf-rest-assert-payload, atf-server, atf-server-catalog-item, atf-server-record

What's new in 4.8.x

This release of the MCP server tracks @servicenow/sdk 4.8.0 and adds support for the following Fluent APIs and SDK enhancements:

• New metadata type: playbook — the PlaybookDefinition API (sys_pd_process_definition, from @servicenow/sdk/automation) for guided, record-driven multi-step processes with lanes, activities, triggers, and inputs/outputs.

• New metadata type: rest-message — the RestMessage API (sys_rest_message) for outbound HTTP integrations with shared auth/headers and callable functions.

• New metadata types: alias and alias-template — the Alias (sys_alias) and AliasTemplate (sys_alias_templates) APIs for Connection & Credential aliases and reusable connection-setup templates.

• New metadata type: retry-policy — the RetryPolicy API (sys_retry_policy) controlling transient-failure handling for connections (fixed-interval, exponential-backoff, or Retry-After).

• New metadata type: data-lookup — the DataLookup API (dl_definition) that auto-copies field values from a matcher table to a source record.

• Declarative deletion (Now.del()) — top-level statement to remove records by coalesce keys or sys_id.

• Type enhancements — $override on DataPolicy/UserPreference; $meta.installMethod on Record/Acl/Alias/UserPreference; ACL field accepts known field names, system columns, or '*'; Table accessibleFrom now defaults to 'public'.

• New CLI tool — query_fluent_records wraps now-sdk query for read-only Table REST queries (JSON envelope output).

Previously (4.7.x)

This release of the MCP server tracks @servicenow/sdk 4.8.0 and adds support for the following Fluent APIs and SDK enhancements:

• New metadata type: data-policy — the DataPolicy API (sys_data_policy2) for server-side mandatory/read-only field enforcement that cannot be bypassed via API, import, or web service.

• Flow error handling & parallelism — wfa.flowLogic.tryCatch, wfa.flowLogic.doInParallel, and wfa.flowLogic.appendToFlowVariables (append to Array.Object flow variables).

• Flow stages — declare stages with FlowStage({ label, value, … }) and activate them in the body via wfa.stage(...) for progress tracking.

• Table augments — add columns to an existing platform/cross-scope table via Table({ augments: '<table>', schema }); added columns must use the current app's ownership prefix: <scope>_ in a named custom scope (for example, x_acme_), or u_ in global and Store-app contexts.

• AI Agent — new agentDescriptor; dataAccess accepts roleMap (role names) or roleList (role sys_ids).

• NASK — securityControls accepts roleMap (role names) alongside roleRestrictions (role sys_ids).

• Universal field override ($override) — escape hatch on Fluent constructors to set unmodeled columns by DB column name.

• Protection policy — protectionPolicy documented on sys_policy-backed APIs (Action, Subflow, business rules, scripted REST, etc.).

• CLI — fluent_transform gains --table/--id (transform by table hierarchy); init gains the typescript.vue template; OAuth client_credentials for CI/CD via SN_SDK_* env vars (see Configuration).

• MCP — read tools now return structuredContent (with declared outputSchema); long-running commands emit progress notifications.

Previously (4.6.0)

Added custom-action, inbound-email-action, sp-header-footer, and sp-page-route-map metadata types; the declarative Form API; subflow-of-subflow and custom actions in flows; AIAF auto-ACL generation; NASK output/input-type enhancements; Table dictionary overrides; and a project-free explain command with tag search, --list, --peek, and --format=raw.

Configuration

Requirements: Node.js 20.18.0+, npm 11.4.1+, @servicenow/sdk 4.8.1

MCP Client Setup

Add to your MCP client configuration file:

{
  "mcpServers": {
    "fluent-mcp": {
      "command": "npx",
      "args": ["-y", "@modesty/fluent-mcp"],
      "env": {
        "SN_INSTANCE_URL": "https://your-instance.service-now.com",
        "SN_AUTH_TYPE": "basic",
        "SN_USER_NAME": "local-username",
        "SN_PASSWORD": "local-password"
      }
    }
  }
}

Client-Specific Locations:

• Claude Desktop / macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• VSCode Copilot: .vscode/mcp.json (use Command Palette: MCP: Add Server...)

• Cursor: Settings → Features → MCP Settings

• Windsurf: Settings → Cascade → MCP Servers → View raw config

• Gemini CLI: ~/.gemini/settings.json

VSCode note: For VSCode, the JSON structure uses "mcp": { "servers": { ... } } instead of "mcpServers".

Environment Variables:

Note: The server automatically detects existing auth profiles matching SN_INSTANCE_URL at startup. If a matching profile is found, it's stored in the session and auto-injected into SDK commands. A new profile is added automatically only when it can complete non-interactively (basic auth with SN_USER_NAME/SN_USERNAME + SN_PASSWORD); otherwise the server emits a single notice with the manual auth --add command to run.

Logging

Once connected, the server sends all logs to the MCP client as notifications/message (the standard MCP logging channel), so they render with the correct severity in your client's UI. Only pre-connection bootstrap lines are written to stderr. Set FLUENT_MCP_LOG_TO_STDERR=1 to additionally mirror every log line to stderr when running headless or debugging outside an MCP client. Use the client's logging/setLevel request to adjust verbosity at runtime (default info; set debug to see raw SDK CLI output).

CI/CD (non-interactive) authentication — SDK v4.7.0+

For headless pipelines, the ServiceNow SDK CLI reads credentials directly from SN_SDK_* environment variables (the MCP server inherits and passes these through to spawned commands — no extra configuration needed). Set SN_SDK_NODE_ENV=SN_SDK_CI_INSTALL to enable CI mode, then:

OAuth uses the client_credentials grant against /oauth_token.do. See the SDK's ci-integration guide (via explain_fluent_api) for instance setup details.

Usage Examples

Typical Workflow

1. Initialize Project

   Create a new Fluent app in ~/projects/asset-tracker for IT asset management

2. Develop with Resources

   Show me the business-rule API specification and provide an example snippet

3. Build and Deploy

   Build the app with debug output, then deploy it

Note: Authentication is automatically configured via environment variables (SN_INSTANCE_URL, SN_AUTH_TYPE). If you need to set up a new auth profile, run: npx @servicenow/sdk auth --add <instance-url> --type <basic|oauth> --alias <alias>

Testing with MCP Inspector

The MCP Inspector provides a web interface for testing MCP servers.

Launch Inspector

# Test published package
npx @modelcontextprotocol/inspector npx @modesty/fluent-mcp

# Or for local development
npm run build && npm run inspect

Test Scenarios

Scenario 1: Explore Business Rule Resources

Objective: Access API specs and code snippets for business rules

Steps:

1. Launch Inspector and wait for server connection

2. Navigate to Resources tab

3. Find and click sn-spec://business-rule in the resource list

4. Review the API specification showing all available methods and parameters

5. Go back and search for sn-snippet://business-rule/0001

6. Click the snippet to view a complete TypeScript example

7. Verify content includes proper imports and follows Fluent patterns

Expected Results:

• API spec displays structured documentation with method signatures

• Snippet shows runnable TypeScript code with ServiceNow metadata patterns

• Content is properly formatted and readable

Scenario 2: Test SDK Info Command

Objective: Verify SDK version and help information retrieval

Steps:

1. Navigate to Tools tab

2. Select sdk_info from the tool list

3. Test Version:

   • Set flag parameter to -v

   • Click Execute

   • Verify response shows the SDK version (e.g., 4.8.1)

4. Test Help:

   • Set flag parameter to -h

   • Set command parameter to build

   • Click Execute

   • Verify response shows build command documentation with options

5. Monitor Notifications pane for command execution logs

Expected Results:

• Version command returns SDK version string

• Help command returns detailed command documentation

• List metadata (-lm) returns available Fluent metadata types

• No errors in notifications pane

• Commands execute within 2-3 seconds

License

MIT