ECM MCP Server

MCP server for B2C ECM - provides live API queries, documentation lookups, diagnostic tools, and write operations for user management.

Setup

npm install
npm run build

Admin vs. customer mode

There are two server builds, not a runtime flag:

| Mode | Entry point | npm package | Required credentials | Hits | | -------- | ------------------------ | -------------------------------- | ------------------------------------------------------------ | ------------------------------------------------ | | Admin | dist/index.js | @crscreditapi/b2c-mcp-server | SCOREAPI_ADMIN_USERNAME + SCOREAPI_ADMIN_PASSWORD | /admin/** — internal KB, all 26 tools | | Customer | dist-customer/index.js | @crscreditapi/b2c-mcp-customer | SCOREAPI_PROD_CUSTOMER_USERNAME + SCOREAPI_PROD_CUSTOMER_PASSWORD (+ optional DEV_ variants) | /customers/** — external KB, reference + portal tools |

The customer entry point sets MCP_CUSTOMER_MODE=true internally — you do not set it yourself. Pick a mode by picking the binary. You can register both side-by-side in .mcp.json if you want to switch between scopes in the same session.

Stdio mode — admin (Claude Code, Cursor, etc.)

Add to your MCP client config (e.g., .mcp.json):

{
	"mcpServers": {
		"scoreapi-admin": {
			"command": "node",
			"args": ["/path/to/b2c-mcp-server/dist/index.js"],
			"env": {
				"SCOREAPI_BASE_URL": "http://localhost:8081/api",
				"SCOREAPI_ADMIN_USERNAME": "your_username",
				"SCOREAPI_ADMIN_PASSWORD": "your_password"
			}
		}
	}
}

Or install as an npm package:

{
	"mcpServers": {
		"scoreapi-admin": {
			"command": "npx",
			"args": ["@crscreditapi/b2c-mcp-server"],
			"env": {
				"SCOREAPI_BASE_URL": "http://localhost:8081/api",
				"SCOREAPI_ADMIN_USERNAME": "your_username",
				"SCOREAPI_ADMIN_PASSWORD": "your_password"
			}
		}
	}
}

Stdio mode — customer

{
	"mcpServers": {
		"scoreapi-customer": {
			"command": "npx",
			"args": ["@crscreditapi/b2c-mcp-customer"],
			"env": {
				"SCOREAPI_PROD_BASE_URL": "https://prod.example.com/api",
				"SCOREAPI_PROD_CUSTOMER_USERNAME": "your_prod_username",
				"SCOREAPI_PROD_CUSTOMER_PASSWORD": "your_prod_password",
				"SCOREAPI_DEV_BASE_URL": "https://dev.example.com/api",
				"SCOREAPI_DEV_CUSTOMER_USERNAME": "your_dev_username",
				"SCOREAPI_DEV_CUSTOMER_PASSWORD": "your_dev_password"
			}
		}
	}
}

HTTP mode (n8n, Docker)

# Admin
MCP_TRANSPORT=http MCP_PORT=3001 node dist/index.js

# Customer
MCP_TRANSPORT=http MCP_PORT=3001 node dist-customer/index.js

Endpoints:

• POST / and POST /mcp — MCP Streamable HTTP transport
• GET /health — Health check

See .env.example for all environment variables.

Tools (26)

| Category | Tools | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Reference | lookup_error_code, lookup_openapi_spec, explain_identity_flow, lookup_knowledge_base | | Customer | get_customer_info, get_customer_hosts, get_customer_stats, get_platform_stats, search_users, get_customer_users_by_period, get_customer_billing_report, get_billing_details | | User | get_user_info, get_user_logs, get_user_features, get_user_identity_status, get_user_reports_history | | Diagnostic | diagnose_user_issue, compare_user_to_host_config | | Write | pause_user, reactivate_user, cancel_user, bulk_pause_users, bulk_resume_users | | Metric | get_metric_stats | | Admin | get_enrollment_failures |

See docs/TOOLS.md for detailed parameter reference.

Resources

The server also exposes 3 MCP resources for direct document access:

| URI | Description | | ------------------------------- | -------------------------------------------------- | | scoreapi://docs/error-codes | All SC* error codes with meanings and remediation | | scoreapi://docs/openapi-spec | Full OpenAPI 3.0 spec for ECM | | scoreapi://docs/identity-flow | DIT -> SMFA -> Enrollment flow documentation |

Customer Package (@crscreditapi/b2c-mcp-customer)

A stripped-down build published separately for customers. Ships the 4 reference tools and 3 resources. lookup_error_code, lookup_openapi_spec, and explain_identity_flow work entirely from bundled data; lookup_knowledge_base calls /customers/knowledge-base/query on b2c-server, so customer credentials are required.

How it works

The customer package uses a separate build pipeline from the same codebase:

| File | Purpose | | -------------------------------- | ----------------------------------------------------------------------------------------------- | | src/index.customer.ts | Entry point — imports only customer tools/handlers | | src/tools/index.customer.ts | Exports only referenceTools from reference.tools.ts | | src/handlers/index.customer.ts | Registers only 4 reference handlers | | tsconfig.customer.json | Compiles to dist-customer/ — TypeScript follows imports, so only reachable files are included | | package.customer.json | npm package metadata (no repository field — keeps GitHub org private) | | README.customer.md | README shown on npmjs.com |

Adding a tool to the customer package

1. Create the tool schema and handler as normal (see "Adding a new tool" above)
2. Import and register in src/tools/index.customer.ts and src/handlers/index.customer.ts
3. Run npm run build:customer to verify only intended files end up in dist-customer/

Build & publish

npm run build:customer    # tsc -p tsconfig.customer.json + copy data/*.json

Both packages are published to npmjs.com on push to main via .github/workflows/publish.yml.

Development

See docs/ARCHITECTURE.md for project structure.