INKY MCP Server
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
INKY MCP Server
A read-only Model Context Protocol server for the INKY email security External API. It is built for everyday MSP email-security work: finding a customer's INKY team, searching what a mailbox received, explaining why a message was delivered or junked, reviewing user-reported mail, auditing allow/block lists, VIPs and console admins, and summarising threat trends for client reports.
It follows the conventions of the WYRE-AI MSP MCP servers (Autotask, IT Glue, Datto RMM, Huntress): the same MCP_TRANSPORT / AUTH_MODE settings, a stateless Streamable HTTP endpoint at /mcp on port 8080, /health, per-request gateway credentials and logs on stderr. See docs/REFERENCE_NOTES.md.
Status: 1.0.0, unreleased. Every tool has been tested against a mocked INKY API that follows the documented response shapes. No live INKY tenant has been queried yet (see Live checks still required). No npm package, GHCR image or registry entry has been published.
What it covers
Verified against the INKY External API 1.15.0 OpenAPI document and the authenticated developer portal (docs/API_NOTES.md).
Area | Tools | INKY API | Stability |
Connection |
|
| stable |
Teams / tenants |
|
| stable |
Billable usage |
|
| stable |
Message search |
|
| beta |
Threat statistics |
|
| beta |
Reported mail |
|
| beta |
Allow / block lists |
|
| beta |
VIPs |
|
| beta |
Console admins |
|
| beta |
Reference |
|
| beta |
Escape hatch |
| any documented GET | — |
INKY's /beta endpoints are fully documented but "may change shape or be removed without notice". The server is read-only: none of INKY's documented write operations (creating rules, remediating reported mail, managing VIPs/admins) are exposed. See Write tools.
Not available from the INKY API (so not offered here): message bodies or attachment downloads, quarantine release, free-text/subject search, outbound mail, webhooks, estate-wide statistics. Details in docs/API_NOTES.md §8.
Related MCP server: mailfact-mcp
Prerequisites
Node.js 22 or later (or Docker).
An INKY API key, created in the INKY console under Settings → API Keys by a Super Admin on the team or organization the key should reach. The key (
inky_ext_…) is shown once.Scope: create the key with your MSP organization selected to reach every customer team beneath it.
Permissions: the default key reads teams and usage only. Choose Custom and tick
readfor the families you want: Messages, Statistics, Reported Mail, Allow List, Block List, VIP List, Admins.inky_reported_mail_item_actionsalso needs Reported Mailremediate(INKY gates that preview with the write permission). Management families need an active Kaseya relationship on the INKY account.Run
inky_test_connectionto see what the key can do.
Your region. INKY runs separate EU and US platforms and a key only works in its own region:
Region | API base URL | Developer portal |
|
|
|
|
|
|
The server only ever sends the key to one of these two origins. Partner HMAC request signing (only for INKY _integration partner keys) is not implemented; console-issued keys do not need it.
Install
git clone https://github.com/FouadHELLAL7/inky-mcp.git
cd inky-mcp
npm ci
npm run buildEnvironment variables
Variable | Default | Description |
| — | INKY API key. Used by stdio and by HTTP with |
|
|
|
| — | Alternative to |
|
|
|
|
| HTTP only. |
|
| HTTP port ( |
|
| HTTP bind address (the Docker image sets |
| — | HTTP gateway auth, WYRE conduit style: every |
| — | HTTP gateway auth for gateways that send fixed headers: every |
| — |
|
|
| Per-request timeout. |
|
| Retries for 429 / 500 / 502–504 and network errors (GET only). |
|
| Longest |
|
| Largest INKY response body read. |
|
| Largest tool result; larger results drop rows from the main list and say so. |
|
| Set |
|
|
|
HTTP refuses to start unless CONDUIT_S2S_SECRET or MCP_BEARER_TOKEN is set (or MCP_ALLOW_INSECURE_DEV=1). Known placeholder values are always refused. See .env.example.
Claude Code
claude mcp add inky -e INKY_API_KEY=inky_ext_your_key -e INKY_REGION=eu -- node /path/to/inky-mcp/dist/index.jsClaude Desktop
claude_desktop_config.json:
{
"mcpServers": {
"inky": {
"command": "node",
"args": ["/path/to/inky-mcp/dist/index.js"],
"env": {
"INKY_API_KEY": "inky_ext_your_key",
"INKY_REGION": "eu"
}
}
}
}An MCP Bundle can be built with npm run pack:mcpb (manifest validated with mcpb validate); it prompts for the key and region.
Docker
Build:
docker build -t inky-mcp .stdio (single user, key from the environment):
docker run -i --rm -e MCP_TRANSPORT=stdio -e INKY_API_KEY=inky_ext_your_key -e INKY_REGION=eu inky-mcpHTTP, gateway mode (the image default; credentials come from each request):
docker run -d --name inky-mcp -p 127.0.0.1:8080:8080 \
-e MCP_BEARER_TOKEN="$(openssl rand -hex 32)" \
-e INKY_REGION=eu \
inky-mcp
curl http://127.0.0.1:8080/healthHTTP, env mode (one shared key in the container):
docker run -d --name inky-mcp -p 127.0.0.1:8080:8080 \
-e AUTH_MODE=env -e INKY_API_KEY=inky_ext_your_key -e INKY_REGION=eu \
-e MCP_BEARER_TOKEN="$(openssl rand -hex 32)" \
inky-mcpdocker compose up -d runs the gateway-mode service from docker-compose.yml (put MCP_BEARER_TOKEN or CONDUIT_S2S_SECRET in .env).
/health (and /healthz) returns {"status":"ok","server":"inky-mcp","version":"1.0.0","transport":"http","authMode":"gateway","timestamp":…}. It needs no credentials and contains no secrets or tenant data.
Gateway setup
In gateway mode (MCP_TRANSPORT=http, AUTH_MODE=gateway) the gateway sends, on every POST /mcp:
Header | Required | Value |
| yes | The INKY API key ( |
| no |
|
| if |
|
| if |
|
If both secrets are configured, either check is accepted. Missing gateway authentication returns 401 before anything else. A missing X-Inky-Api-Key returns 401 {"error":"Missing credentials","required":["X-Inky-Api-Key"]}; the environment key is never used as a fallback. Each request gets its own MCP server instance with that request's credentials, so concurrent callers with different keys or regions never share state (covered by test/http.test.ts).
Adding it next to Autotask, IT Glue and Datto RMM
Run the container on the same Docker network as your other MCP servers, named
inky-mcp, withMCP_BEARER_TOKEN(orCONDUIT_S2S_SECRETfor a WYRE conduit gateway) andINKY_REGION=eu.Store the INKY API key and the bearer token in the gateway's secret store.
Add an HTTP upstream:
id / namespace:
inkyURL:
http://inky-mcp:8080/mcpheaders (secret references, never raw values):
Authorization: Bearer <reference to the MCP_BEARER_TOKEN secret>X-Inky-Api-Key: <reference to the INKY API key secret>X-Inky-Region: eu
Refresh the catalog. All 24 tools are read-only (
readOnlyHint: true), so viewer-level grants are appropriate.
Alternatively run the container with AUTH_MODE=env and INKY_API_KEY set, like a single-tenant upstream, and only send the Authorization header from the gateway.
Tools and example calls
All tools return JSON text. Lists return returned, has_more and next_cursor. Pass next_cursor back as cursor to the same tool with the same filters to get the next page; a null next_cursor is the end.
Tool | Purpose | Example arguments |
| Key scope, permissions, rotation/expiry, rate-limit headers |
|
| Region, origin, key configured?, INKY reachability |
|
| Tools grouped by domain |
|
| Resolve a customer by name or domain |
|
| Estate tree ( |
|
| What did this mailbox receive and what did INKY decide? |
|
Find every copy of a reported or SIEM message |
| |
Dangerous mail that reached the inbox |
| |
| Monthly client report: verdict split, peak days, top reasons |
|
| Daily counts by verdict, reason or result category |
|
| Open user-reported mail, newest first |
|
What happened to this message? (includes closed records) |
| |
| Full record with items and user reports |
|
| Preview allow/block rules INKY would create (no changes) |
|
| Allow-anything rules across the estate |
|
Why was this sender allowed for one team (incl. inherited)? |
| |
| Block rules for a domain |
|
| VIP and console-admin audits |
|
| Verdict codes ↔ console labels |
|
| Billable mailboxes, license reconciliation |
|
| GET any documented endpoint |
|
Typical investigation: inky_teams_find → inky_messages_search (recipient + window) → detail=true on the suspicious copy → inky_allow_list_list with team_id to see whether a rule let it through → inky_reported_mail_list with its rfc822_message_id.
inky_raw_request safety
GET only. path must be relative and match one of the 27 documented INKY GET templates (writes such as :remediate or :batch cannot match). Scheme/host, //, .., backslashes, query strings or fragments in path, encoded / or ., and double encoding are rejected before any request. Dynamic segments are decoded once and re-encoded, the final URL is checked against the configured INKY origin, redirects are never followed, and the caller's own key, timeout, retry and size limits apply.
Pagination, rate limits and errors
Page sizes: teams, usage, allow/block, VIPs, admins: 1–999 (INKY default 50). Messages and reported mail: 1–100 (default 25). Statistics return the whole window (≤ 90 days) without paging.
Windows: message search defaults to the last 7 days, at most 90 days per call. Statistics cover closed UTC days (default the last 30 ending yesterday, at most 179 days back). Reported mail defaults to 7 days of activity.
Rate limits are per INKY node plus an organization-wide budget, with no published numbers. On
429 RATE_LIMITED(and 500/503) the server waitsRetry-Afterand retries up toINKY_MAX_RETRIEStimes. Waits longer thanINKY_MAX_RETRY_WAIT_SECONDSare returned to the model instead.POLLED_TOO_SOON(re-reading the same reported-mail first page within 60 s) is never retried; pass the previouspoll_fromasupdated_sinceinstead.Errors come back as
isErrorresults with INKY'scode, HTTP status,request_id(quote it to INKY support) and guidance. Examples:INVALID_API_KEY(wrong region?),FORBIDDEN(permission missing, checkinky_test_connection),NOT_FOUND(absent or outside the key's scope).Output: long text fields are clipped, embedded lists are capped (e.g. 25 links per message), and results over
INKY_MAX_OUTPUT_CHARSdrop trailing rows with anoutput_truncatednote.Privacy: keys, cookies and authorization headers are never logged or returned. INKY keys in error text are masked to their 16-character prefix, and message content is never logged.
Write tools
None. INKY documents write endpoints (allow/block rule create/modify/delete, VIP and admin management, reported-mail remediate/dismiss/review/apply). All of them are /beta and change mail-flow policy or console access across customer estates. Adding them would be a separate, opt-in change behind INKY_ENABLE_WRITE_TOOLS=true, with destructive annotations and testing against a non-production tenant first.
Troubleshooting
Symptom | Fix |
| Key and region don't match ( |
| Add that family's |
| The INKY account lacks the Kaseya relationship needed for management families. Contact INKY. |
|
|
| Use |
HTTP server exits at start | Set |
Gateway gets 401 | Check the |
stdio client shows garbage | Nothing in this server writes to stdout except JSON-RPC; check wrappers. |
Development
npm run lint # eslint
npm run typecheck # tsc incl. tests
npm test # vitest (mocked INKY API)
npm run build
npm run smoke # MCP SDK client over stdio and HTTP against a mock INKY API
npm run spec:fetch # download INKY's OpenAPI document to openapi/ (git-ignored)CI (.github/workflows/ci.yml) runs all of the above on Node 22 and 24, builds the Docker image and runs the smoke test against the container over stdio and HTTP. The release workflow is manual-only and pushes to GHCR only when dispatched with confirm: publish.
Live checks still required
Built without access to an INKY API key. Mocked tests cover request construction, errors, retries, pagination, tools and gateway isolation; only the unauthenticated GET /v1/status was called live (EU and US). Before relying on it, run with a real key:
inky_test_connectionin each region you use (confirms auth header and/v1/meshape).inky_teams_list/inky_teams_findon an organization-scoped key.inky_messages_searchwith an org nodeteam_idand withdetail=true.inky_threat_summaryon a team;inky_statistics_getwith an org node (expect 422).inky_reported_mail_listtwice within 60 s (expectPOLLED_TOO_SOONexplained).inky_allow_list_list/inky_block_list_listwith and withoutteam_id.inky_vips_list,inky_admins_list,inky_result_types_list,inky_usage_history.Rate-limit headers and
X-API-Key-Expires-Soonsurfacing ininky_test_connection.The gateway path end to end through your MCP gateway.
License
Apache-2.0. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Scopable MSP API: clients, quotes, assessments, compliance, QBRs. OAuth 2.1, read-only or read-write
Read-only MCP access to sessions, funnels, campaigns, errors, live visitors, and anomalies.
Read-only IT Health Check, domain security, recommendations, pricing, and draft enquiries.
Read-only access to your Oppira competitor posts, ads, reviews, alerts and marketing plan.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to manage MSP-multi-tenant email security: organizations, domains, users, licensing, features, subscription packages, and email flow reporting.Apache 2.0

mailfact-mcpofficial
AlicenseAqualityCmaintenanceProvides read-only access to a Mailfact tenant, letting users list domains, sending sources, and aggregate reports, and query DMARC alignment, reporter coverage, and record-level data through MCP tools. It returns counts and rows only, without recommending policies or scoring domains.915 npmMIT- AlicenseNot gradedqualityBmaintenanceEnables MSPs and security teams to manage customer tenants, licenses and usage billing, and to run security operations such as searching events and secured emails, maintaining allow/block exception rules, and quarantining or restoring messages. It is exposed as a stateless, multi-tenant Streamable HTTP endpoint that takes credentials per request via headers.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to read protected computers and their check-ins, computer groups, approval requests, the unified audit log, and child organizations through a zero-trust endpoint security portal API. Every operation is read-only, with credentials supplied per request as headers and never stored.Apache 2.0