@meridiantoolkit/mcp

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.

Install

cd meridian-mcp
npm install
npm run build

Or once published:

npx @meridiantoolkit/mcp

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 npm publish --provenance. Uses npm's Trusted Publishing (OIDC) — no NPM_TOKEN secret to create or rotate.

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.1 --generate-notes   # publishing this release triggers the workflow