Ironbrain.Mcp 0.2.17

dotnet tool install --global Ironbrain.Mcp --version 0.2.17
                    
This package contains a .NET tool you can call from the shell/command line.
dotnet new tool-manifest
                    
if you are setting up this repo
dotnet tool install --local Ironbrain.Mcp --version 0.2.17
                    
This package contains a .NET tool you can call from the shell/command line.
#tool dotnet:?package=Ironbrain.Mcp&version=0.2.17
                    
nuke :add-package Ironbrain.Mcp --version 0.2.17
                    

Ironbrain.Mcp (ironbrain-mcp)

stdio MCP server for the Ironbrain platform (HITL Outbox). Bots authenticate with an Ironbrain account (Supabase JWT) and enqueue actions for human confirmation — they do not hold IMAP/SMTP secrets.

Distinct from Ironbrain.MailCal.Mcp / ironbrain-mailcal (local mail/calendar with adapter secrets on the bot host).

Prefer this package (or HTTP POST /api/mcp) over MailCal when the same capability exists on the platform — secrets stay server-side and Freigabe stays in Ironbrain.

Current package version: 0.2.14 (CAP propose: no approvalUrl on failed proposals; OpenAI openai_insufficient_quota vs openai_rate_limit reasonCodes).
nuget.org may lag until PM Trusted Publishing ships 0.2.14 — see docs/mcp.md § Maintainer publish.

Hosts on Missing vs current
0.2.0 get_action, Freigabe read grant, connectors, trash/reject, OAuth redirect fix
0.2.1 Connector admin tools, enqueue_mcp_tool, enqueue_trash_email, reject_action, OAuth redirect_uri fix (0.2.2+)
0.2.2 (in-repo only) Same tool set as 0.2.3; use 0.2.3 for the published catch-up
dotnet tool update -g Ironbrain.Mcp
# pin when needed:
dotnet tool update -g Ironbrain.Mcp --version 0.2.3

Restart the MCP server (or start a new Cloud Agent thread) so tools/list refreshes.

Bot bootstrap (catalog visibility)

After Connect / auth succeeds:

  1. Call whoami → check authenticated and short capabilitiesSummary (readyToolCount, availableWriteActionCount, canEnqueueSendEmail, allowMcpConfirm, hint).
  2. Call list_available_actions → full catalog (same as GET /api/capabilities: accounts, tools, actions + availability / reasonCode / HITL fields).
  3. Only then call enqueue_* / read tools. Do not fall back to MailCal MCP just because the catalog was never queried.

Cloud Agents: prefer remote Streamable HTTP at https://app.ironbrain.de/api/mcp (same tools). Stdio ironbrain-mcp is for local desktop / optional Cloud fallback.

Changelog

0.2.14

  • propose_capability: when proposal status ≠ pending_approval, returns error + reasonCode and omits approvalUrl / freigabeMarkdown (hosted MCP and this package; published 0.2.13 still showed Freigabe links on failures).
  • OpenAI CAP pipeline failures map to openai_insufficient_quota vs openai_rate_limit (and openai_http_error) from proposal errorMessage — no API key leakage.
  • get / list enrichment no longer invents Freigabe URLs for non-pending rows.

0.2.10

  • list_emails: server-side filters (unread, since/before, fromContains, subjectContains, mailbox); JSON page object { items, totalCount, offset, limit, nextOffset } (not a bare array)
  • enqueue_move_email / enqueue_archive_email: optional emailIds for bulk (one Outbox action, same AllowAuto ~0.8 policy)
  • get_email: returns inReplyTo + references; missing UID → HTTP 404
  • enqueue_add_appointment: recurrence (recurrenceRule or recurrenceFrequency + count/until); omitted timeZoneId → Europe/Berlin

0.2.9

  • Per-action Freigabe deep links: pending enqueue_*, get_action, and each list_pending_actions item include approvalUrl / approvalMarkdown pointing at {PublicWebBaseUrl}/outbox/{actionId} (default https://app.ironbrain.de/outbox/{id}).

0.2.8

  • External-recipient HITL hard floor: externalSendRequiresUiApproval on capabilities / enqueue responses. Send/Reply/Forward, send-like enqueue_mcp_tool, and write-kind connector tools with any email in args (deep scan) outside org verified_email_domains / own addresses cannot auto-apply. Confirm requires Angular X-Ironbrain-Ui-Session (MCP OAuth client_id tokens rejected even with a forged header). Approve in web Outbox under a user session.
  • enqueue_send_email accepts optional cc / bcc (evaluated by the hard floor).

0.2.7

  • enqueue_update_appointment / enqueue_delete_appointment (UID + calendarId; optional recurrenceId for one occurrence)
  • list_appointments returns recurrenceId / isRecurring
  • HITL defaults: update matches AddAppointment (AllowAuto ~0.8); delete is RequireHitl (always Freigabe)

0.2.6

  • OAuth callback page: branded success/error HTML on the local redirect host (http://127.0.0.1:8765/callback) with a CTA to app.ironbrain.de.

0.2.5

  • enqueue_save_draft: IMAP APPEND into Drafts with \Draft (no SMTP send). From = IMAP account identity. Default HITL AllowAuto @ confidence ≥ 0.8.
  • get_email: returns To, Cc, Message-ID (via API + Ironbrain.Email 0.1.3).

0.2.4

  • enqueue_forward_email: ForwardEmail HITL; original attachments fetched on confirm.

0.2.3

  • NuGet ↔ HTTP parity: ship connector admin tools, enqueue_mcp_tool, enqueue_trash_email, reject_action that were already on POST /api/mcp / main but not on nuget.org 0.2.1.
  • Docs: bot bootstrap via whoami.capabilitiesSummary + list_available_actions; prefer platform MCP over MailCal.
  • Includes 0.2.2 OAuth authorize redirect_uri fix (never published separately).

0.2.2

  • Fix OAuth authorize redirect_uri double-encoding (%253A… → invalid_redirect_uri). Authorize URL is built with a single EscapeDataString pass; browser open uses /usr/bin/open argv on macOS. Plain IRONBRAIN_OAUTH_REDIRECT_URI only (not pre-encoded).
  • Default OAuth scopes → openid only until custom ironbrain.* scopes are registered on the Supabase OAuth client (prod currently returns unsupported scope: ironbrain.api). Override with IRONBRAIN_OAUTH_SCOPES when allowlisted.

0.2.1

  • get_action: GET /api/outbox/actions/{id} — bots learn approve vs deny (terminal statuses) and read grantToken after Freigabe confirm.
  • Read tools accept pending_freigabe envelopes when HITL ≠ AllowAlways; optional confidence / rationale; after confirm re-call with grantToken (sent as X-Ironbrain-Read-Grant).
  • Docs: docs/mcp.md, docs/outbox.md §7.2.

0.2.0

  • Documents and ships the full MailCal platform-parity tool set already on main (email reads, calendar reads, move/archive/reply/add-appointment enqueue).
  • Calendar reads: multi-calendar still requires calendarId per call — no silent all-calendar aggregate (web merges after per-id).
  • whoami returns structured auth/connection errors (auth_failed / connection_failed + hint) instead of opaque MCP failures; auth probe uses capabilities only.
  • tools/list confirm-gate fails open (hides confirm_action) when the capabilities probe errors, so discovery is not blocked by a brief API outage; HTTP clients use a 15s timeout.
  • OAuth 2.1 + PKCE (Supabase AS): preferred auth via IRONBRAIN_OAUTH_CLIENT_ID; dual support with legacy password grant / IRONBRAIN_ACCESS_TOKEN (IRONBRAIN_AUTH_MODE=auto|oauth|legacy). See docs/mcp-oauth.md.

0.1.0

  • Initial platform MCP: whoami, list_pending_actions, enqueue_send_email, capabilities catalog.

Tools (v0.2.5)

Tool Behavior
list_available_actions Mirrors GET /api/capabilities (accounts/tools/actions + reasonCodes; allowMcpConfirm)
list_emails / get_email IMAP reads; default AllowAlways. When HITL ≠ AllowAlways → pending_freigabe; poll get_action, then re-call with grantToken (X-Ironbrain-Read-Grant). get_email includes To, Cc, Message-ID, and attachment metadata (name/type/size).
list_calendars / list_appointments CalDAV reads; same HITL / grant pattern; calendarId required when multiple calendars
enqueue_send_email Creates a pending SendEmail Outbox action via POST /api/outbox/actions (catalog-guarded; optional accountId)
enqueue_move_email / enqueue_archive_email / enqueue_trash_email HITL MoveMail / ArchiveMail / TrashMail (IMAP); no mutate on enqueue; optional envelope preview*
enqueue_reply_email HITL ReplyEmail (source message id + draft To/Subject/body); SMTP only after Freigabe
enqueue_forward_email HITL ForwardEmail (source UID + To + optional note); original attachments fetched from IMAP on Freigabe confirm
enqueue_save_draft HITL SaveDraft (IMAP APPEND to Drafts with \Draft; no send); From = IMAP identity; optional replyToMessageId for threading
enqueue_add_appointment HITL AddAppointment (summary/start/end + required calendarId); CalDAV only after Freigabe
enqueue_update_appointment HITL partial update by uid + calendarId; optional recurrenceId for one occurrence
enqueue_delete_appointment HITL delete series or one occurrence (recurrenceId); always Freigabe (RequireHitl)
enqueue_mcp_tool External connector mcp:{connectorId}:{toolName} via Outbox/HITL; Google/API secrets stay on Api
list_pending_actions Lists pending/refining Outbox actions (includes draft preview + MCP Freigabe). Terminal statuses omitted — use list_actions / get_action.
list_actions ACT-History: filtered/paged Outbox list (status, since, type, accountId, decision, limit/offset). Read-only.
get_action GET /api/outbox/actions/{id} any status (approve vs deny learning; read grantToken after Freigabe confirm)
reject_action Always on. POST …/reject — cancel pending Freigabe (no side effect). Not gated by allow_mcp_confirm.
whoami Verifies auth; returns connection metadata + capabilitiesSummary (no secrets). Failures return structured JSON + hint.
list_connectors / get_connector / create_connector / update_connector / set_connector_secrets / refresh_connector_tools / enable_connector / disable_connector Org connector admin. create/enable are UI hard-floored (403 for MCP) — prefer propose_capability. See docs/external-mcp-connectors.md / docs/design/cap-dynamic.md.
propose_capability / list_capability_proposals / get_capability_proposal / reject_capability_proposal CAP-Dynamic: propose external MCP capability → Freigabe approval URL. Never enables. No approve_* on MCP.
confirm_action Opt-in only (allow_mcp_confirm, default false). Absent from tool lists unless opted in. Prefer web Outbox / Draft cards.

Today’s calendar (per calendar)

Multi-calendar accounts must query one calendar at a time. Do not assume MCP aggregates all calendars (the web UI merges after per-id fetches; an optional MCP helper is not in this package yet).

1. list_calendars
2. For each calendar id → list_appointments(date="today", calendarId=<id>, range="day")
3. Merge / present results in the client if you need a combined “today” view

Install / update (refresh Cursor mcp.json)

After NuGet publish (Trusted Publishing / PM) or from a local pack:

# From nuget.org (after Trusted Publishing of 0.2.3)
dotnet tool update -g Ironbrain.Mcp
# or first-time:
dotnet tool install -g Ironbrain.Mcp

# From a packed nupkg (pre-publish / CI artifact)
dotnet tool update -g Ironbrain.Mcp --add-source /path/to/nupkg-dir --version 0.2.3
# or:
dotnet tool install -g Ironbrain.Mcp --add-source /path/to/nupkg-dir --version 0.2.3

Then point Cursor MCP command at ironbrain-mcp (on PATH after global install) and restart the MCP server so the tool list refreshes.

Pack from repo:

dotnet pack Ironbrain.Mcp/Ironbrain.Mcp.csproj -c Release -o ./artifacts

Do not publish to NuGet until Product Manager / Mattanja GO. Publish only via GitHub Actions Trusted Publishing (OIDC) — no classic API keys. See docs/mcp.md § Maintainer publish.

Auth

Preferred: OAuth 2.1 Authorization Code + PKCE against Supabase Auth (AS). Ironbrain.Api is the Resource Server only — no Ironbrain /oauth/token. See docs/mcp-oauth.md.

Mode Env / config Status
OAuth + PKCE IRONBRAIN_SUPABASE_URL, IRONBRAIN_SUPABASE_ANON_KEY, IRONBRAIN_OAUTH_CLIENT_ID (optional IRONBRAIN_REFRESH_TOKEN) Preferred
Access token IRONBRAIN_ACCESS_TOKEN (short-lived Supabase JWT) Deprecated for interactive MCP; CI/emergency OK
Password grant IRONBRAIN_SUPABASE_URL + anon key + IRONBRAIN_EMAIL / IRONBRAIN_PASSWORD Deprecated (legacy until hard cutover)

IRONBRAIN_AUTH_MODE=auto|oauth|legacy (default auto: prefer OAuth when oauthClientId is set). Soft warnings in logs / whoami when legacy is used.

Also set IRONBRAIN_API_BASE_URL (default https://localhost:7065/api). For local HTTPS with a dev cert, set IRONBRAIN_ALLOW_INSECURE_TLS=true.

Config file alternative: ~/.config/ironbrain/platform.json or $IRONBRAIN_PLATFORM_CONFIG (oauthClientId, optional refreshToken).

See docs/mcp.md and docs/mcp-oauth.md.

Cursor MCP snippet

{
  "mcpServers": {
    "ironbrain": {
      "command": "ironbrain-mcp",
      "env": {
        "IRONBRAIN_API_BASE_URL": "https://localhost:7065/api",
        "IRONBRAIN_ALLOW_INSECURE_TLS": "true",
        "IRONBRAIN_SUPABASE_URL": "http://127.0.0.1:54321",
        "IRONBRAIN_SUPABASE_ANON_KEY": "<anon-key>",
        "IRONBRAIN_OAUTH_CLIENT_ID": "<public-client-id>"
      }
    }
  }
}

Demo path

  1. Call list_available_actions (or whoami for a short summary) — expect allowMcpConfirm: false by default.
  2. Bot calls enqueue_send_email (optional accountId from the catalog).
  3. Open ironbrain-web → Outbox (/outbox) — Freigabe still works with MCP confirm disabled.
  4. Confirm / Edit / Reject. Confirm runs SMTP with the account’s platform email settings.

Without SMTP configured, enqueue returns a structured missing_smtp / missing_config error and creates no Outbox row.

To enable MCP confirm (customer risk acceptance): org admin PUT /api/organizations/{id}/mcp-confirm with { "allowMcpConfirm": true }.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

This package has no dependencies.

Version Downloads Last Updated
0.2.17 99 11/4/2026
0.2.15 119 10/28/2026
0.2.14 112 10/21/2026
0.2.13 101 10/21/2026
0.2.12 104 10/21/2026
0.2.11 110 10/21/2026
0.2.7 111 10/20/2026
0.2.6 114 10/15/2026
0.2.4 115 10/6/2026
0.2.3 115 10/5/2026
0.2.1 123 9/29/2026
0.2.0 117 9/29/2026

0.2.17 — stdio host exits when the parent/client process is gone (parent-PID watch) in
addition to stdin EOF, so orphaned ironbrain-mcp instances do not linger (or spin) after
the MCP client disconnects. See #147.
0.2.16 — list_mailboxes (AllowAlways read) + enqueue_create_mailbox (RequireHitl write;
idempotent IMAP CREATE). Requires Ironbrain.Email 0.1.15.
0.2.15 — enqueue_add/update_appointment: send startText/endText (original strings) so the API
interprets offset-less times as wall-clock in timeZoneId (default Europe/Berlin). Avoids
DateTimeOffset JSON attaching +00:00 on UTC hosts (events were 1h late).
0.2.14 — CAP propose: when status ≠ pending_approval return error + reasonCode and NO approvalUrl
(fixes published 0.2.13 which still linked Freigabe on failed proposals). OpenAI CAP failures
surface openai_insufficient_quota vs openai_rate_limit (and openai_http_error) from errorMessage.
0.2.13 — CAP-Dynamic: propose_capability / list_capability_proposals / get_capability_proposal /
reject_capability_proposal (+ approval URL). create_connector / enable_connector documented as
UI hard-floored (403 for MCP); prefer propose_capability.
0.2.12 — enqueue_add_appointment / enqueue_update_appointment: optional allDay (VALUE=DATE,
exclusive end yyyy-MM-dd). list_appointments returns allDay + date-only start/end. Requires
Ironbrain.Calendar 0.1.13.
0.2.11 — list_actions: Outbox history with status/since/type/accountId/decision filters + paging
(ACT-History). Slim list projection (no payloadJson / resultJson / grantToken).
0.2.10 — MAIL-Triage + post-#82 follow-ups: list_emails filters + totalCount/nextOffset;
enqueue_move/archive emailIds (bulk, same HITL); get_email In-Reply-To/References + HTTP 404
for missing UID; enqueue_add_appointment recurrence (RRULE / daily|weekly+count|until);
omitted timeZoneId defaults to Europe/Berlin (no floating offset drop). Requires Email/Calendar 0.1.7.
list_emails returns page object {items,totalCount,offset,limit,nextOffset} (not a bare array).
0.2.9 — Per-action Freigabe deep links: approvalUrl / approvalMarkdown on pending enqueue_*,
get_action, and each list_pending_actions item (/outbox/{actionId} from PublicWebBaseUrl).
0.2.8 — External-recipient HITL hard floor: enqueue_send_email Cc/Bcc; capabilities
externalSendRequiresUiApproval; MCP-scoped tokens cannot confirm external sends.
0.2.7 — enqueue_update_appointment / enqueue_delete_appointment (partial CalDAV update +
delete; recurrenceId for one occurrence; update AllowAuto ~0.8, delete RequireHitl).
list_appointments returns recurrenceId / isRecurring.
0.2.6 — Polish local OAuth callback page (127.0.0.1:8765/callback): branded success/error
UI with CTA to https://app.ironbrain.de/.
0.2.5 — enqueue_save_draft (SaveDraft HITL; IMAP APPEND \\Draft; From=IMAP identity).
get_email returns To, Cc, Message-ID (via API/mailcal 0.1.3).
0.2.4 — enqueue_forward_email (ForwardEmail HITL; original attachments fetched on confirm).
0.2.3 — Catch up NuGet tool surface with HTTP MCP (POST /api/mcp): connector admin
tools, enqueue_mcp_tool, enqueue_trash_email, reject_action. Document bot bootstrap:
whoami.capabilitiesSummary + list_available_actions. Prefer platform MCP over MailCal
when the same capability exists. Includes 0.2.2 OAuth redirect_uri fix.
0.2.2 — Fix OAuth authorize URL redirect_uri double-encoding (invalid_redirect_uri).
Build authorize query with a single EscapeDataString pass; open browser via argv
(/usr/bin/open) instead of UseShellExecute FileName=url. Reject already-encoded
IRONBRAIN_OAUTH_REDIRECT_URI. Default OAuth scopes → openid only until custom
ironbrain.* scopes are registered on the Supabase OAuth client (unsupported scope
otherwise). See docs/mcp-oauth.md.
0.2.1 — get_action + Freigabe read grant surface (code from #36; package bump for nuget.org).