SubscriberAPI Server

An MCP (Model Context Protocol) server that lets GitHub Copilot CLI query SFMC SubscriberAPI execution logs — health checks, email lookups, execution traces, and recent errors.

Who is this for?

SFMC developers and engineers who want to troubleshoot SubscriberViaAPI issues from the terminal using natural language, for example:

• "Is the SubscriberAPI log endpoint healthy?"
• "Find recent errors for source MyForm."
• "Get the execution trace for FormRequestID abc-123."

Prerequisites

• Node.js 18 or later
• GitHub Copilot CLI
• SFMC log API endpoint URL and API key (from your team's CloudPage / API setup)

Quick start

1. Clone the repo

git clone https://github.com/YOUR-ORG/subscriberapi-mcp.git
cd subscriberapi-mcp

Tip: Clone to a folder without spaces in the path (e.g. C:\dev\subscriberapi-mcp) to avoid Windows path issues.

2. Install and build

npm run setup

3. Add your credentials

cp .env.example .env

Edit .env and set:

• SFMC_LOG_ENDPOINT — your SFMC execution log API URL
• SFMC_LOG_API_KEY — your API key

Never commit .env. It is already in .gitignore.

4. Use with GitHub Copilot CLI

This repo includes a project-level MCP config (.mcp.json) with a relative path — no machine-specific paths required.

From the cloned repo folder, start Copilot:

copilot

Copilot auto-loads .mcp.json when you work in this project. You should see subscriberapi with a green checkmark under MCP Servers.

5. Test it

Inside Copilot:

Use subscriberapi health_check and tell me the result.

Or from the shell (one-shot):

copilot -p "Call subscriberapi health_check" --allow-all-tools

MCP tools

Tool	Description
health_check	Check if the SFMC log endpoint is available
get_executions_by_email	Find executions by email (optional source, date range, limit)
get_execution_trace	Get full trace for a formRequestId
get_recent_errors	List recent errors (optional filters)

How configuration works

File	Purpose
.mcp.json	Shared Copilot MCP config (relative dist/index.js, no secrets)
.env	Private API credentials (each developer creates their own)
~/.copilot/mcp-config.json	Optional global Copilot MCP config (user-specific)

Recommended: Rely on .mcp.json in the repo. Each developer only needs their own .env.

If you previously added subscriberapi to your global ~/.copilot/mcp-config.json with an absolute path, remove it to avoid duplicates:

copilot mcp remove subscriberapi

Optional: global install (any folder)

If you want subscriberapi available outside this repo, register it once from the cloned folder:

Windows (PowerShell):

.\scripts\register-copilot-mcp.ps1

macOS / Linux:

./scripts/register-copilot-mcp.sh

These scripts read credentials from your .env and register an absolute path on your machine only.

Development

npm run dev    # run TypeScript directly (tsx)
npm run build  # compile to dist/
npm start      # run compiled server

Troubleshooting

Issue	Fix
Red X on subscriberapi	Run npm run build so dist/index.js exists
Missing SFMC_LOG_ENDPOINT	Create .env from .env.example
Path split at space (Windows)	Clone to a path without spaces, or use the register script
Permission denied in -p mode	Add --allow-all-tools
Duplicate subscriberapi servers	Run copilot mcp remove subscriberapi for the global entry

License

ISC