fagents-mcp

MCP (Model Context Protocol) server exposing email tools to Claude Code agents. Handles SMTP sending and IMAP reading, with per-agent credential isolation and an audit-logged secure email gate.

Stack: TypeScript, Node.js, Express, @modelcontextprotocol/sdk. Stateless MCP over HTTP.

Tools

Related MCP server: mailpouch

Architecture

Claude agent (MCP client)
  │  POST /mcp  (x-api-key: <agent-token>)
  ▼
fagents-mcp (Express + MCP SDK)
  ├─ auth.ts     — resolve agent from API key
  ├─ config.ts   — load per-agent env from agents.json, AsyncLocalStorage context
  ├─ email.ts    — SMTP send via nodemailer
  ├─ imap.ts     — IMAP read/search/download via node-imap
  └─ server.ts   — MCP tool registration, gate_email audit logging

Stateless: Each MCP request creates a fresh server+transport instance. No session state between calls.

Per-agent credentials: Each agent sends its unique API key. The server resolves the agent ID, then loads that agent's credentials (SMTP host/pass, IMAP host/pass, etc.) from agents.json via AsyncLocalStorage. Agents never see each other's credentials.

Credential Storage

Credentials live in agents.json in the working directory (typically the installation directory). This file is managed by the human operator — agents must not read or write it directly.

{
  "agents": {
    "ftf": {
      "apiKey": "<hashed-or-raw-key>",
      "SMTP_HOST": "smtp.example.com",
      "SMTP_USER": "ftf@example.com",
      "SMTP_PASS": "...",
      "IMAP_HOST": "imap.example.com",
      "IMAP_USER": "ftf@example.com",
      "IMAP_PASS": "...",
      "COMMS_TOKEN": "...",
      "COMMS_URL": "http://127.0.0.1:9754"
    }
  },
  "shared": {
    "SMTP_PORT": "587",
    "IMAP_PORT": "993"
  }
}

AgentConfig accepts any [envKey: string]: string pairs alongside apiKey — the schema is open for extension (Telegram tokens, etc.).

Environment Variables

Without agents.json, the server falls back to environment variables:

Setup

npm install
npm run build        # compiles TypeScript → dist/

# Single-agent mode (env vars)
MCP_API_KEY=secret SMTP_HOST=smtp.example.com ... node dist/server.js

# Multi-agent mode (agents.json in working dir)
node dist/server.js

Development (no build step):

npm run dev          # runs src/server.ts directly via tsx

Claude Code Integration

Add to .claude/settings.json (or via MCP config):

{
  "mcpServers": {
    "fagents-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "x-api-key": "<your-agent-api-key>"
      }
    }
  }
}

MCP tools are discovered at session start. After changing tools or restarting the server, start a new Claude session to pick up changes.

Security Notes

• gate_email strips <untrusted> tag variants from email body before wrapping content — prevents boundary escape attacks from malicious emails.

• Subject and messageId are excluded from gate_email response (attacker-controlled fields that could carry injection payloads). They are logged to #email-log for human review.

• agents.json should be chmod 600 and never committed to version control.

• Server binds 127.0.0.1 by default. Use SSH tunnels or a reverse proxy for remote access.

Origin

Part of the fagents project — autonomous Claude Code agent infrastructure. Built by freeturtle agents and Juho Muhonen.