Skip to content

MCP_README.md

Latest commit

 

History

History
275 lines (194 loc) · 6.06 KB

MCP_README.md

File metadata and controls

275 lines (194 loc) · 6.06 KB
Raw

Dynobox MCP Reference

This document describes the Dynobox MCP server so external agents can connect and automate inbox workflows on top of Dynobox.

Overview

  • Transport: JSON-RPC 2.0 over HTTP POST
  • MCP endpoint: http://localhost:3001/api/mcp
  • Metadata endpoint: http://localhost:3001/api/mcp/metadata
  • Protocol version: 2024-11-05
  • Batch JSON-RPC requests: not supported

The MCP server is available through the existing Dynobox backend process.

Security and Headers

Dynobox may require these headers depending on environment:

  • x-account-id: required when multiple accounts are configured.
  • x-dynobox-key: required only if DYNOBOX_API_KEY is set on the server.

By default Dynobox only accepts loopback clients unless ALLOW_REMOTE_CLIENT=true.

Connection Flow (Recommended)

  1. Call initialize
  2. Call tools/list
  3. Optionally call tools/call with dynobox_list_accounts to resolve account IDs
  4. Call tools/call for operational tools

JSON-RPC Methods

initialize

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "my-agent",
      "version": "1.0.0"
    }
  }
}

tools/list

Request:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

tools/call

Request:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "dynobox_search_threads",
    "arguments": {
      "accountId": "you@example.com",
      "query": "invoice OR receipt",
      "unreadOnly": true,
      "label": "INBOX",
      "maxResults": 10
    }
  }
}

Tool Catalog

dynobox_list_accounts

List configured Dynobox accounts.

Arguments: none

dynobox_list_threads

List recent threads for an account.

Arguments:

  • accountId?: string
  • query?: string
  • label?: string (default INBOX)
  • labelId?: string
  • pageToken?: string
  • maxResults?: number (1-25)
  • fast?: boolean

dynobox_search_threads

Search threads using query and structured filters.

Arguments:

  • accountId?: string
  • query?: string
  • unreadOnly?: boolean
  • from?: string
  • to?: string
  • subject?: string
  • label?: string
  • maxResults?: number (1-25)
  • pageToken?: string

dynobox_filter_threads

Filter threads by label/mailbox and optional unread/sender/recipient fields.

Arguments:

  • accountId?: string
  • label?: string
  • labelId?: string
  • unreadOnly?: boolean
  • from?: string
  • to?: string
  • maxResults?: number (1-25)
  • pageToken?: string

dynobox_get_thread

Fetch full thread content/messages.

Arguments:

  • threadId: string (required)
  • accountId?: string

dynobox_send_message

Send message or reply through the target account provider.

Arguments:

  • accountId?: string
  • to: string (required)
  • cc?: string
  • bcc?: string
  • subject?: string
  • body: string (required)
  • isHtml?: boolean
  • threadId?: string
  • inReplyTo?: string
  • references?: string
  • attachments?: Array<{ filename?: string; mimeType?: string; data?: string }>

dynobox_thread_action (Gmail accounts)

Apply thread actions.

Arguments:

  • accountId?: string
  • threadId: string (required)
  • action: "archive" | "trash" | "untrash" | "markRead" | "markUnread" | "star"

dynobox_list_labels (Gmail accounts)

List Gmail labels.

Arguments:

  • accountId?: string
  • includeStats?: boolean

dynobox_update_thread_labels (Gmail accounts)

Add/remove labels on a Gmail thread.

Arguments:

  • accountId?: string
  • threadId: string (required)
  • addLabelIds?: string[]
  • removeLabelIds?: string[]

At least one of addLabelIds or removeLabelIds is required.

dynobox_list_contacts (Gmail accounts)

List Google contacts.

Arguments:

  • accountId?: string

dynobox_get_profile (Gmail accounts)

Get Gmail profile information.

Arguments:

  • accountId?: string

Tool Response Shape

Successful tool responses are returned in MCP-compatible format with content and structuredContent.

If a tool fails, Dynobox returns result.isError = true and a textual error message in result.content.

cURL Examples

Set shell vars first:

export DYNOBOX_MCP_URL="http://localhost:3001/api/mcp"
export DYNOBOX_ACCOUNT_ID="you@example.com"
# Optional only if DYNOBOX_API_KEY is enabled on server:
# export DYNOBOX_API_KEY="your-shared-key"

Initialize:

curl -sS "$DYNOBOX_MCP_URL" \
  -H "Content-Type: application/json" \
  -H "x-account-id: $DYNOBOX_ACCOUNT_ID" \
  ${DYNOBOX_API_KEY:+-H "x-dynobox-key: $DYNOBOX_API_KEY"} \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"cli-agent","version":"1.0.0"}}}'

List tools:

curl -sS "$DYNOBOX_MCP_URL" \
  -H "Content-Type: application/json" \
  -H "x-account-id: $DYNOBOX_ACCOUNT_ID" \
  ${DYNOBOX_API_KEY:+-H "x-dynobox-key: $DYNOBOX_API_KEY"} \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

Search unread invoices:

curl -sS "$DYNOBOX_MCP_URL" \
  -H "Content-Type: application/json" \
  -H "x-account-id: $DYNOBOX_ACCOUNT_ID" \
  ${DYNOBOX_API_KEY:+-H "x-dynobox-key: $DYNOBOX_API_KEY"} \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"dynobox_search_threads","arguments":{"accountId":"'"$DYNOBOX_ACCOUNT_ID"'","query":"invoice OR receipt","unreadOnly":true,"label":"INBOX","maxResults":10}}}'

Send a message:

curl -sS "$DYNOBOX_MCP_URL" \
  -H "Content-Type: application/json" \
  -H "x-account-id: $DYNOBOX_ACCOUNT_ID" \
  ${DYNOBOX_API_KEY:+-H "x-dynobox-key: $DYNOBOX_API_KEY"} \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"dynobox_send_message","arguments":{"accountId":"'"$DYNOBOX_ACCOUNT_ID"'","to":"recipient@example.com","subject":"Hello from Dynobox MCP","body":"Quick test from an agent."}}}'

Metadata Endpoint

GET /api/mcp/metadata returns server name/version, endpoint URLs, required headers, and tool summaries. Agents can use this to auto-configure.