ChangeCrab

Posted on May 6

OpenClaw + Changelog: A Technical Integration Guide for Developer Teams with ChangeCrab

#changelog #softwaredevelopment #ai #node

Most changelog workflows fail for one reason: context switching.

Engineers ship in terminals and IDEs, then switch to a web UI to publish release notes. Product and DevRel teams draft updates in docs, then manually re-enter them in changelog tools. The friction is small each time, but high across a quarter.

If your team already runs OpenClaw, the ChangeCrab MCP server gives you a clean bridge:

OpenClaw orchestrates agent behavior and tool calls
MCP provides the protocol boundary
ChangeCrab MCP tools expose changelog operations over stdio
ChangeCrab API remains the source of truth for write operations

TL;DR: What You'll Need

OpenClaw CLI: Installed and configured (Node 22.14+ required, Node 24 recommended).

ChangeCrab Account: An active paid plan or trial.

API Key: Generated from ChangeCrab Settings -> API Keys.

Architecture: how requests actually flow

At runtime, the integration is a straightforward process chain:

OpenClaw loads an MCP server definition from its registry.
That definition launches changecrab-mcp-server as a stdio process.
OpenClaw sees ChangeCrab tools in its callable tool set.
When a user prompt implies changelog work, OpenClaw invokes a tool.
ChangeCrab MCP server translates that tool call into ChangeCrab HTTP API calls.
API responses are returned to OpenClaw as MCP tool output.

The key point: OpenClaw is orchestrator, ChangeCrab MCP server is translator, and ChangeCrab API is the system of record.

Prerequisites and version baseline

OpenClaw runtime and bootstrap

OpenClaw's recommended install path:

npm install -g openclaw@latest
openclaw onboard --install-daemon

OpenClaw currently documents Node 24 as recommended, with Node 22.14+ supported.

ChangeCrab account requirements

ChangeCrab API access is paid/trial only. You need:

an active paid plan or trial
an API key from Settings -> API Keys

ChangeCrab MCP server runtime

ChangeCrab MCP server package currently declares:

Node >=18
stdio MCP transport
required env var: CHANGECRAB_API_KEY

OpenClaw MCP registry: precise behavior and commands

OpenClaw's mcp set/list/show/unset commands manage stored MCP server definitions in OpenClaw config.

Important detail from OpenClaw docs: these commands manage config state; they do not guarantee the target server is reachable at command time.

Register ChangeCrab (npx path)

openclaw mcp set changecrab '{"command":"npx","args":["-y","changecrab-mcp-server"],"env":{"CHANGECRAB_API_KEY":"cc_your_api_key_here"}}'

Register ChangeCrab (local build path)

openclaw mcp set changecrab '{"command":"node","args":["/absolute/path/to/changecrab/mcp-server/dist/index.js"],"env":{"CHANGECRAB_API_KEY":"cc_your_api_key_here"}}'

Inspect and validate registration

openclaw mcp list
openclaw mcp show changecrab --json

Remove configuration

openclaw mcp unset changecrab

Tool profile implications in OpenClaw

OpenClaw documents that configured bundle MCP tools are available in normal coding and messaging profiles, but not in minimal.

So if the server is configured correctly but tools never appear in agent runs, check profile first.

Operationally:

minimal -> expect no bundled MCP tools
coding / messaging -> bundled MCP tools can be exposed
explicit deny policies can still block tool access

ChangeCrab MCP server internals (verified from source)

The server registers tool families in src/index.ts:

changelogs (registerChangelogTools)
posts (registerPostTools)
categories (registerCategoryTools)
static info tools (registerInfoTools)

It exits immediately when CHANGECRAB_API_KEY is missing.

Transport and process model

MCP server over stdio (StdioServerTransport)
process is intended to be spawned/owned by client runtime

API base and auth

From src/api.ts:

default base URL: https://changecrab.com/api
override via CHANGECRAB_API_BASE_URL (useful for testing)
auth header: X-API-Key

Retry behavior

Network requests use bounded retry logic:

max retries: 3
delay: incremental (500ms * attempt)
retryable classes include transient network errors (ECONNRESET, ETIMEDOUT, etc.)

Error mapping

Mapped status behaviors include:

401 -> invalid/missing API key guidance
403 -> subscription required guidance
404 -> resource not found/access denied guidance
>=500 -> service unavailable guidance

Exact tool surface (10 tools)

The current server test suite verifies a 10-tool surface:

list_changelogs
get_changelog
list_categories
list_posts
create_post
update_post
delete_post
get_changecrab_overview
get_changecrab_api_info
get_changecrab_limits_summary

This is useful for CI assertions when upgrading OpenClaw, MCP SDK, or the server package.

Tool-to-endpoint mapping (API contract view)

ChangeCrab API routes expose these core endpoints under authenticated middleware:

GET /changelogs
GET /changelogs/{id}
GET /changelogs/{id}/categories
GET /changelogs/{id}/posts
POST /changelogs/{id}/posts
PUT /changelogs/{id}/posts/{postId}
DELETE /changelogs/{id}/posts/{postId}

Docs endpoint:

[https://changecrab.com/api/documentation](https://changecrab.com/api/documentation)

A subtle but important write-path detail

In create_post and update_post, the server first fetches changelog details (GET /changelogs/{id}) and derives team from that response before writing.

This means post writes are effectively a two-step sequence:

resolve team context from changelog
execute post create/update with required fields (summary, markdown, team, plus visibility flags/categories)

For developers debugging write failures, this extra dependency is critical.

Production-grade setup patterns

Pattern A: managed package install (fastest path)

Good for most teams:

openclaw mcp set changecrab '{"command":"npx","args":["-y","changecrab-mcp-server"],"env":{"CHANGECRAB_API_KEY":"cc_live_key"}}'

Pros:

no local build step
easy to roll forward

Tradeoff:

runtime depends on package resolution/network behavior in your environment

Pattern B: pinned local artifact (more control)

Build once in your infra pipeline:

cd mcp-server
npm install
npm run build

Then register exact artifact path:

openclaw mcp set changecrab '{"command":"node","args":["/opt/integrations/changecrab-mcp/dist/index.js"],"env":{"CHANGECRAB_API_KEY":"cc_live_key"}}'

Pros:

deterministic binary path
simpler rollback/change management

Security and secret handling

API key placement

Prefer environment injection in MCP config (env) over inline prompt usage.

Principle of least privilege

Use a dedicated ChangeCrab API key for automation workflows; rotate if exposed.

Avoid accidental leakage

Do not echo full openclaw mcp show ... --json outputs in shared logs if they include inline secrets.

OpenClaw trust boundary

OpenClaw docs emphasize that MCP registry config and MCP runtime behavior are distinct concerns. Validate both:

definition exists (mcp show)
runtime/profile actually enables tool invocation

End-to-end validation checklist

After setup, validate in order:

Config saved:
- openclaw mcp list includes changecrab
Definition shape:
- openclaw mcp show changecrab --json
Profile supports MCP:
- not minimal
Read path works:
- ask OpenClaw to run list_changelogs
Write path works:
- create a draft post in a known changelog
Update/delete lifecycle:
- update then delete a test post

For local server testing, ChangeCrab also includes npm test in mcp-server/, which validates MCP handshake and tool registration behavior.

Prompting patterns that work well for teams

Use explicit IDs and intent to reduce back-and-forth:

"List changelogs and include IDs."
"For changelog <id>, list categories and recent posts."
"Create draft post in changelog <id> with summary X and markdown Y."
"Update post <post_id> in changelog <id> with this body, keep it draft."
"Publish by setting draft=0 and public=1."

When you need partial updates, remember current update_post behavior expects full required post fields, so pull current values first.

Failure modes and fast remediation

Startup fail: missing key

Symptom:

MCP process exits with required env var error

Fix:

ensure CHANGECRAB_API_KEY is present in registered server env

401 on API tools

Symptom:

read/write tools fail immediately

Fix:

check key validity and whitespace issues

403 on API tools

Symptom:

auth succeeds but access denied

Fix:

confirm account is on paid/trial plan with API access

Tools appear missing

Symptom:

OpenClaw cannot call ChangeCrab tools

Fix:

verify registry definition
verify profile is not minimal
verify no deny policy suppresses bundled MCP tools

Post write errors despite valid key

Symptom:

create/update fails after apparent auth success

Fix:

verify changelog ID exists and is accessible
verify team resolution from changelog works
verify payload includes required fields

Operational recommendations for larger teams

If multiple people share the same OpenClaw deployment:

use environment-specific keys (dev/staging/prod)
pin local artifact paths in production
add a canary run that calls list_changelogs after upgrades
keep a non-production changelog for integration tests

If you automate release publishing:

keep generation and publication steps separate
default to draft=1 for generated content
require explicit approval prompt to publish

Reference command block

# Register
openclaw mcp set changecrab '{"command":"npx","args":["-y","changecrab-mcp-server"],"env":{"CHANGECRAB_API_KEY":"cc_your_api_key_here"}}'

# Inspect
openclaw mcp list
openclaw mcp show changecrab --json

# Remove
openclaw mcp unset changecrab