@yoryoboy/connectif-mcp

@yoryoboy/connectif-mcp is a minimal Model Context Protocol server that exposes the official Connectif HTTP API to MCP clients over stdio. It is a thin wrapper: requests use Connectif's official routes and parameter names, and upstream responses are returned without business transformations.

Quick start

Create a Connectif API key with the scopes required by the operations you use.
Add this server to your MCP client's standard mcpServers configuration:

{
  "mcpServers": {
    "connectif": {
      "command": ["pnpm", "dlx", "@yoryoboy/connectif-mcp"],
      "env": {
        "CONNECTIF_API_KEY": "key-id:key-secret"
      }
    }
  }
}

Restart the MCP client. pnpm dlx downloads and runs @yoryoboy/connectif-mcp when needed.

Keep credentials in the client's environment configuration or another secret store. Never commit a real API key.

Requirements

Node.js 20 or newer
A Connectif API key with the scopes required by the operations you use
An MCP client that supports stdio servers

Installation

Install the package directly when you want it in a project:

npm install @yoryoboy/connectif-mcp
pnpm add @yoryoboy/connectif-mcp

For a global installation alternative, run npm install --global @yoryoboy/connectif-mcp and configure the command as connectif-mcp. Direct npx shorthand may fail to resolve scoped package bins in some environments, so pnpm dlx is the recommended zero-install launcher.

Configuration

npm install
npm run build
CONNECTIF_API_KEY='key-id:key-secret' npm start

The server reads these environment variables:

Variable	Required	Default	Description
`CONNECTIF_API_KEY`	Yes	None	Sent as `Authorization: apiKey {value}`.
`CONNECTIF_BASE_URL`	No	`https://api.connectif.cloud`	API origin; useful for mocked or compatible environments.
`CONNECTIF_TIMEOUT_MS`	No	`10000`	Request abort timeout in milliseconds.

Tools and actions

The server registers exactly 12 domain tools and 45 non-deprecated Connectif operations. Each tool takes an action property that selects the official operation; route parameters, query parameters, JSON bodies, and multipart fields remain in their corresponding locations.

Tool	API area
`connectif_contacts`	Contacts
`connectif_purchases`	Purchases
`connectif_products`	Products
`connectif_exports`	Exports
`connectif_imports`	Imports
`connectif_coupon_sets`	Coupon sets
`connectif_workflows`	Workflows
`connectif_store`	Store
`connectif_contact_fields`	Contact fields
`connectif_custom_events`	Custom events
`connectif_custom_integrations`	Custom integrations
`connectif_custom_event_types`	Custom event types

Example:

{
  "action": "getContactByEmail",
  "email": "[email protected]"
}

For imports, the file tool value contains a filename and base64 content, and the server converts it to the official multipart file part. See ENDPOINTS.md for the complete operation catalog and docs/API_REFERENCE.md for Connectif API behavior.

Security and fidelity

API keys are read from the environment and are not logged or included in tool arguments by the server.
Paths are encoded, fixed routes are selected from the operation registry, and arbitrary route overrides are not accepted.
Successful results preserve the upstream HTTP status, headers, and body. HTTP errors preserve the same upstream metadata in an MCP error result.
The wrapper does not add retries, rate-limit handling, response projection, business middleware, or other policy beyond the request timeout.
Never put API keys in source control, URLs, tool arguments, or logs. Use .env.example as a variable reference only.

Development

npm run format:check
npm run typecheck
npm test
npm run build
pnpm pack --dry-run

Tests use mocked HTTP and do not require credentials or network access.

License

MIT. See LICENSE.

@yoryoboy/connectif-mcp