How do I use SubscriberAPI MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@SubscriberAPI MCP Server Check the health of the SubscriberAPI log endpoint" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

SubscriberAPI MCP Server

by soumyaranjansingh-economist

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

SubscriberAPI MCP 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."

Related MCP server: GitHub Copilot MCP Server

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

Available Tools

4 tools

get_executions_by_emailB

Find SubscriberViaAPI executions by email address, optionally filtered by source and date range.

ParametersJSON Schema

Name	Required	Description	Default
`emailAddress`	Yes
`source`	No
`startDate`	No
`endDate`	No
`limit`	No
`includeFullTrace`	No

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It does not mention read-only nature, side effects, authorization needs, rate limits, or return format. The description is too minimal for a search tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with 13 words, free of extraneous information. It efficiently states the core purpose without redundancies.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 6 parameters, no output schema, and no annotations, the description is insufficient. It should explain return values, pagination (limit), trace inclusion (includeFullTrace), and required permissions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 0%. The description mentions 'email address', 'source', and 'date range' but does not explain the format or semantics of parameters like startDate, endDate, limit, or includeFullTrace. Only emailAddress is partially clarified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (Find), the resource (SubscriberViaAPI executions), and the primary filter (by email address). It distinguishes from sibling tools such as get_execution_trace and get_recent_errors by specifying a unique filtering criterion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when needing executions by email, but does not explicitly state when to use this tool versus alternatives or provide exclusion criteria. No guidance on when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_execution_traceB

Get the execution trace for one FormRequestID.

ParametersJSON Schema

Name	Required	Description	Default
`formRequestId`	Yes
`includeFullTrace`	No

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided; description does not disclose any behavioral traits (e.g., read-only, side effects) beyond stating it gets a trace.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no unnecessary words, direct to the point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Missing output schema, no annotations, and no explanation of what the execution trace contains or the impact of includeFullTrace; incomplete for a tool with two parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%; description only mentions 'one FormRequestID', failing to explain the purpose or effect of the includeFullTrace boolean parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clear verb ('Get') and resource ('execution trace'), specifies it's for a single FormRequestID, distinguishing it from siblings like get_executions_by_email and get_recent_errors.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use vs alternatives; context only implies it's for a specific ID, but no exclusions or when-not-to-use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_recent_errorsC

Find recent SubscriberViaAPI errors, optionally filtered by source and date range. Returns summaries by default.

ParametersJSON Schema

Name	Required	Description	Default
`source`	No
`startDate`	No
`endDate`	No
`limit`	No
`includeFullTrace`	No

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Only mentions default return type; lacks disclosure of behavior differences with includeFullTrace, meaning of 'recent', or potential side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with no fluff, but missing critical information that could be added concisely.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Incomplete given 5 parameters, no output schema, and lack of annotations; fails to explain return structure, pagination, or error handling.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only two parameters vaguely referenced; no details on formats, valid values, or default behaviors beyond limit and includeFullTrace defaults.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'Find recent SubscriberViaAPI errors', specifying verb and resource. Implicitly distinguishes from siblings focused on executions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use vs alternatives; no prerequisites or limitations mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

health_checkA

Check whether the SFMC SubscriberAPI execution log endpoint is available.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A3.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description must disclose all behavior. It only states the check action without explaining what constitutes availability (e.g., response format, error behavior, side effects).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, short sentence that directly conveys the purpose with no unnecessary words. Front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters and no output schema, the description is minimally adequate but lacks details on return format or expected outcomes, which would be helpful for an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters and schema coverage is 100%, so no additional meaning is needed. Baseline score 4 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Check whether...available') and resource ('SFMC SubscriberAPI execution log endpoint'), clearly differentiating from sibling tools that retrieve executions, traces, or errors.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied (to test endpoint availability) but no explicit when-to-use, when-not-to-use, or comparison to siblings is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

4 tool updatesv1.0.0Jun 23, 2026
- First observedget_execution_trace
- First observedget_executions_by_email
- First observedget_recent_errors
- First observedhealth_check

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.6/5.0

Scored 2026-06-23 15:30 across 4 tools

Disambiguation5/5

Each tool targets a distinct operation: lookup by email, trace retrieval, error fetching, and health check. There is no overlap, and the descriptions clearly differentiate them.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern using snake_case, such as get_executions_by_email, get_execution_trace, get_recent_errors, and health_check.

Tool Count5/5

With 4 tools, the set is well-scoped for a focused log viewer API. Each tool serves a clear purpose without being sparse or overwhelming.

Completeness4/5

The set covers key operations for querying executions, traces, and errors, plus health check. A minor gap is the lack of an unfiltered execution list, but the core workflow is functional.

Maintenance

ActivityStale

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

salesforce-devopsOAuth
cloud.serpent
Plan Salesforce deploys, open pull requests and trigger pipelines from your AI client.
CI/CD & DevOps Version Control CRM
2
kodey-ai-salesforce-mcp-minimal
ai.smithery
Run SOQL queries to explore and retrieve Salesforce data. Access accounts, contacts, opportunities…
Databases Customer Data Platforms ERP Systems
2
kodey-ai-salesforce-mcp-server
ai.smithery
Run SOQL queries against your Salesforce org to retrieve records and insights. Explore objects, fi…
Databases Customer Data Platforms ERP Systems
2
kodey-ai-salesforce-mcp
ai.smithery
Run SOQL queries to explore and retrieve Salesforce data. Inspect records, fields, and relationshi…
Databases Customer Data Platforms ERP Systems
2

Related MCP Servers

Salesforce CLI MCP Server
Command Line Cloud Platforms Developer Tools
codefriar
A
license
A
quality
D
maintenance
Exposes Salesforce CLI functionality to LLM tools like Claude Desktop, allowing AI agents to execute Salesforce commands, manage orgs, deploy code, and query data through natural language.
Updated 7 months ago (2026-02-14 07:39 UTC)
5
17 npm
36
ISC
GitHub Copilot MCP Server
Developer Tools Code Analysis
Poorgramer-Zack
A
license
Not graded
quality
C
maintenance
Integrates GitHub Copilot CLI with MCP clients to offer various coding assistance tools including asking questions, explaining code, suggesting commands, debugging, refactoring, generating tests, and reviewing code.
Updated 5 months ago (2026-04-23 02:27 UTC)
14 npm
8
MIT
copilot-mcp-server
Code Analysis Developer Tools Command Line
x51xxx
A
license
C
quality
D
maintenance
Connects MCP-enabled editors to GitHub Copilot CLI for non-interactive code analysis, batch processing, and code review.
Updated 9 months ago (2025-12-02 00:24 UTC)
10
19 npm
5
MIT
mcp-copilotcli-history
MicroMichaelIE
A
license
A
quality
C
maintenance
Enables searching and analyzing GitHub Copilot's conversation history stored locally, providing tools for full-text search, session listing, statistics, and file-based retrieval.
Updated 9 months ago (2025-12-05 14:03 UTC)
6
4
MIT