Skip to main content
Glama

@meridiantoolkit/mcp

meridian-mcp MCP server

MCP server for the Meridian business-services platform. Exposes services, service requests, workflow steps, payments and meetings as Model Context Protocol tools and resources. MCP is a protocol, not a host-specific plugin format — this server runs unchanged in Claude Code, Codex CLI, Claude Desktop, pi, or any other MCP-compatible client.

Listed on the official MCP Registry as io.github.meridian-silkdev/meridian-mcp, and on Glama.

Install

cd meridian-mcp
npm install
npm run build

Or once published:

npx @meridiantoolkit/mcp

Related MCP server: Relay

Configure

Copy .env.example or set env vars directly:

Var

Description

Default

MERIDIAN_API_URL

Meridian app base URL

http://localhost:3000

MERIDIAN_API_KEY

mrd_ API key (Better Auth) for REST calls

(none — tools return placeholder hint until set)

DATABASE_URL

Optional direct DB access fallback

MERIDIAN_MCP_LOG_LEVEL

debug/info/warn/error

info

More: /.well-known/agent-configuration exposes Agent Auth discovery (capability-based, short-lived JWTs, device-auth/CIBA approval). Agents can use either a long-lived mrd_ key or scoped Agent Auth grants — see meridian-skills meridian-api skill.

Without MERIDIAN_API_KEY every tool still responds — it explains what endpoint would be called and what to configure, so the server is safe to run in dry-run / demo mode.

Run

npm start            # stdio MCP server
npm run dev          # watch mode via tsx

Claude Code

claude mcp add meridian -- node /absolute/path/to/meridian-mcp/dist/index.js
# or, once published:
claude mcp add meridian -- npx -y @meridiantoolkit/mcp

Or drop a .mcp.json in your project root (shareable with a team, checked into git):

{
  "mcpServers": {
    "meridian": {
      "command": "npx",
      "args": ["-y", "@meridiantoolkit/mcp"],
      "env": {
        "MERIDIAN_API_URL": "http://localhost:3000",
        "MERIDIAN_API_KEY": "..."
      }
    }
  }
}

Codex CLI

Codex reads MCP servers from ~/.codex/config.toml (or a project-scoped .codex/config.toml for a trusted project):

[mcp_servers.meridian]
command = "npx"
args = ["-y", "@meridiantoolkit/mcp"]
env = { MERIDIAN_API_URL = "http://localhost:3000", MERIDIAN_API_KEY = "..." }

Or via the CLI: codex mcp add meridian -- npx -y @meridiantoolkit/mcp. The same config is shared by Codex CLI, the IDE extension, and the ChatGPT desktop app.

Codex has no plugin/skill system (unlike Claude Code and pi) — its equivalent of meridian-plugin/meridian-skills is just this MCP server plus project guidance. Copy AGENTS.md.example into your project's AGENTS.md for the same tool-usage guidance the skills packages give elsewhere.

Claude Desktop / pi

Add to your MCP config (Claude Desktop: claude_desktop_config.json; pi: .pi/settings.json → mcpServers, or pi --mcp):

{
  "mcpServers": {
    "meridian": {
      "command": "node",
      "args": ["/absolute/path/to/meridian-mcp/dist/index.js"],
      "env": {
        "MERIDIAN_API_URL": "http://localhost:3000",
        "MERIDIAN_API_KEY": "..."
      }
    }
  }
}
pi --mcp meridian-mcp/dist/index.js
# or via npx after publish
npx @meridiantoolkit/mcp

Tools

Tool

Description

meridian_status

Check API connectivity/config and list available tools/resources. No params. Works the same in every client — this replaces the pi-only meridian_status extension tool from meridian-plugin so status-checking isn't tied to one host.

list_services

List services (filter: categorySlug, isActive, countryCode)

get_service

Get service by id/slug with formConfig

list_categories

List service categories

list_service_requests

List requests (filter: status, customerId, providerId, limit)

get_service_request

Get request by id with steps

create_service_request

Create request (serviceId, answers, customTitle)

update_request_status

Patch request status (prefer advance_step)

get_workflow_status

Current phase + all requestSteps

advance_step

Complete current step → next step

list_request_steps

All RequestSteps in order

get_payment_status

Payment row for a request

verify_payment

Server-side verify with Flouci (Tunisia, local) or Stripe (international)

list_meetings

List meetings (filter: serviceRequestId, status)

create_meeting

Create Teams meeting + invites

respond_to_meeting

RSVP ACCEPTED/DECLINED/PENDING

Resources

URI

Description

meridian://services

Service catalog JSON

meridian://workflow

Workflow backbone + phases

Development

npm run typecheck
npm run build
npm test          # spawns the built server over stdio and exercises every tool/resource

Publish

First publish (manual, one-time — a scoped package can't use Trusted Publishing until it exists on the registry):

npm login                     # once per machine
npm publish --access public

CI/CD

  • .github/workflows/ci.yml — every push to main and every PR: npm ci, typecheck, build, npm test (the real stdio smoke suite).

  • .github/workflows/publish.yml — fires on a published GitHub Release, re-runs the full test suite, checks the release tag matches package.json's version, then:

    1. npm publish --provenance via npm's Trusted Publishing (OIDC) — no NPM_TOKEN secret to create or rotate.

    2. Publishes/updates the listing on the official MCP Registry via mcp-publisher login github-oidc + mcp-publisher publish (also OIDC, no secret). server.json's version is synced to the release tag automatically. This step has continue-on-error: true — the registry is explicitly in preview, so a hiccup there never blocks the actual npm release.

mcpName requirement: package.json has an "mcpName": "io.github.meridian-silkdev/meridian-mcp" field — the registry's package validator needs this to confirm the npm package and the GitHub-verified server identity are published by the same owner. If you ever rename the server in server.json, update this field too or publishes will 400.

Known upstream bug, worked around: the interactive mcp-publisher login github device flow reliably 403s when publishing under a GitHub organization namespace (confirmed-public membership, Owner role, doesn't matter — see modelcontextprotocol/registry#1537, still open as of this writing). github-oidc from inside a GitHub Actions workflow running in the org's own repo sidesteps it entirely, since it verifies the workflow's repo identity rather than checking the human account's org list. That's why the registry publish step lives in CI, not as a manual local command.

One-time setup after the first manual publish: on the package's npmjs.com page → Settings → Trusted Publisher → GitHub Actions, and point it at meridian-silkdev/meridian-mcp, workflow publish.yml. After that, releasing a new version is just:

npm version patch   # or minor/major — bumps package.json + creates a git tag
git push --follow-tags
gh release create v0.1.3 --generate-notes   # publishing this release triggers both the npm and MCP Registry publish steps

Available Tools

16 tools
advance_stepA

Advance the current step for a request to the next step (completes current step and moves currentStepId). Validates phase transitions.

Inputs: requestId (required), stepId.

create_meetingA

Create a meeting with title, scheduledAt (ISO), duration minutes, optional serviceRequestId, and invite selection (customer/provider). Creates Teams meeting via Graph and sends invites immediately.

Inputs: title (required), duration (required), scheduledAt (required), description, +3 more.

create_service_requestA

Create a new service request. Needs serviceId (or slug) and answers matching the service formConfig.

Inputs: serviceId (required), answers, customTitle.

get_payment_statusA

Get payment state for a service request (Payment row: amount, status, provider, serviceRequestId unique). Returns verification status — never trust redirect alone.

Inputs: requestId (required).

get_serviceA

Get a single Meridian service by id or slug, including formConfig and delivery steps.

Inputs: idOrSlug (required).

get_service_requestB

Get a single service request by id, including current step, phase, and requestSteps.

Inputs: id (required).

get_workflow_statusA

Get the workflow state for a request: current phase, current step, and all requestSteps with status (PENDING/IN_PROGRESS/COMPLETED). Status is derived from currentStepId → phase.

Inputs: requestId (required).

list_categoriesA

List Meridian service categories (name, slug, icon, isActive, sortOrder, countryCode).

Inputs: no named parameters.

list_meetingsC

List meetings. Filter by serviceRequestId, status, or participant userId. Meetings are created with a fixed title/time/duration and explicit invites (customer/provider/both).

Inputs: status, serviceRequestId.

list_request_stepsA

List all RequestSteps for a request in order, including key, phase, assignedTo, stepType, status, startedAt, completedAt.

Inputs: requestId (required).

list_service_requestsC

List service requests. Filter by status (DRAFT, REQUIREMENTS, ADMIN_VALIDATION, PROVIDER_ACCEPTANCE, QUOTE, PAYMENT, DELIVERY, FULFILLMENT, COMPLETED, DISPUTED, CANCELLED), customerId, providerId.

Inputs: limit, status, customerId, providerId.

list_servicesA

List Meridian services. Filter by category slug, active flag, or country code (e.g. TN, FR, PT).

Inputs: isActive, countryCode, categorySlug.

meridian_statusA

Check Meridian API connectivity (MERIDIAN_API_URL + MERIDIAN_API_KEY) and list available tools/resources. No params.

Inputs: no named parameters.

respond_to_meetingA

Record RSVP for a meeting (ACCEPTED/DECLINED/PENDING). Declining records your answer but does NOT cancel the meeting.

Inputs: response (required), meetingId (required).

update_request_statusA

Advance or set a request's status. Prefer advance_step for workflow transitions. Use only when you know the target phase is valid.

Inputs: id (required), status (required), reason.

verify_paymentA

Verify a payment with the provider (Flouci for Tunisia — local wallet/card — or Stripe for international cards). Triggers server-side verification — redirect back to the portal alone is never proof of payment.

Inputs: requestId (required), paymentId.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 16 tools

    Disambiguation3/5

    Most tools target distinct resources, but there is notable overlap between update_request_status and advance_step, and between get_workflow_status, list_request_steps, and get_service_request (all expose step/phase data). The descriptions help clarify intent, but an agent could still select the wrong tool for workflow inspection or transition.

    Naming Consistency4/5

    The set mostly follows a clear verb_noun pattern: list_*, get_*, create_*, update_*, verify_*. Minor deviations like meridian_status (no verb) and advance_step (imperative without the request object) break the pattern slightly, but the style is generally predictable.

    Tool Count4/5

    With 16 tools, the server is slightly above the ideal 3-15 range, but the count is justified by the broad domain covering service catalog, requests, workflow state, payments, and meetings. Each tool addresses a meaningful operation, so the size feels reasonable rather than bloated.

    Completeness4/5

    The tool surface covers the main service request lifecycle: listing services, creating requests, advancing workflow, checking payments, and managing meetings. Minor gaps exist such as no dedicated cancel/delete operation, no way to update service request answers, and limited meeting management beyond RSVP, but agents can work around these with existing tools.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Exposes internal company services as LLM-callable MCP tools, enabling AI agents to perform business operations like customer management, order processing, and support ticketing through natural language.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to access a unified catalog of tools from various APIs (OpenAPI, GraphQL, MCP, Google Discovery) through the MCP protocol.
      12 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Exposes Azure AI Foundry agents, workflows, and AI Search vector-database capabilities as MCP tools, enabling natural language interaction with agents, semantic search, and index management.
      10
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to register, send/receive email, store encrypted credentials, emit audit events, and query behavioral trust scores via MCP tools.
      5
      MIT