ScoreAPI MCP Server

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

Setup

npm install
npm run build

Configuration

Stdio mode (Claude Code, Cursor, etc.)

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

{
  "mcpServers": {
    "b2c-scoreapi": {
      "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": {
    "b2c-scoreapi": {
      "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"
      }
    }
  }
}

HTTP mode (n8n, Docker)

MCP_TRANSPORT=http MCP_PORT=3001 node dist/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 ScoreAPI | | scoreapi://docs/identity-flow | DIT -> SMFA -> Enrollment flow documentation |

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

A stripped-down build published separately for customers. Contains only the 4 reference tools and 3 resources — zero API code, no credentials needed.

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.