monarch-mcp-custom/.deployment.md

Monarch MCP Custom — Deployment Guide

Internal / Private. Not for public distribution. This doc covers how the local Komodo deployment works and how to operate it.

---

Architecture

Git push to main
    |
    v
Gitea Actions (.gitea/workflows/build.yaml)
    |
    v
Docker build + push to gitea.ext.ben.io/b3nw/monarch-mcp-custom:latest
    |
    v
Komodo Stack "monarch-mcp" pulls image and deploys
    |
    v
Container runs on host port 8070 (mapped to container 8000)

---

Gitea Build Workflow

File: .gitea/workflows/build.yaml

Triggers on every push to main or master:

1. Checks out the repo
2. Logs into gitea.ext.ben.io container registry (uses secrets.CR_PAT)
3. Builds and pushes gitea.ext.ben.io/b3nw/monarch-mcp-custom:latest

Manual Build Trigger

If you need to force a rebuild without a code change, push an empty commit:

git commit --allow-empty -m "chore: trigger rebuild"
git push origin main

Or edit .gitea/workflows/build.yaml and push.

---

Komodo Stack Deployment

Stack Name: monarch-mcp Server: 6942f06939bbe4eb5a9f21aa (main Docker host) Image: gitea.ext.ben.io/b3nw/monarch-mcp-custom:latest Host Port: 8070 → Container 8000

Environment Variables (from .env)

Variable	Purpose	Source
MONARCH_TOKEN	Session token for Monarch Money API	Extract from browser DevTools
MONARCH_EMAIL	Account email for re-auth fallback	Plaintext
MONARCH_PASSWORD	Account password for re-auth fallback	Plaintext
MONARCH_MFA_SECRET	TOTP secret for re-auth fallback	Plaintext (from 2FA setup)
MONARCH_PORT	Host port mapping (default 8070)	.env
LOG_LEVEL	Python logging level (INFO/DEBUG)	.env

How to Redeploy

Via Komodo UI:

1. Navigate to Stacks → monarch-mcp
2. Click Deploy (or Pull then Deploy to force fresh image)

Via MCP / API:

# Using the komodo_mcp tool
DeployStack(stack="monarch-mcp")

Force fresh image pull: The stack has auto_pull: true, so a standard Deploy should pull the latest image. If not, use Pull Stack first.

---

Container Operations

Check Logs

Via Komodo UI: Stack → monarch-mcp → Logs → Select service monarch-mcp

Via Komodo API:

GetStackLog(stack="monarch-mcp", services=["monarch-mcp"], tail=50)

Health Check

The container exposes a health endpoint:

curl http://localhost:8070/health
# Expected: {"status": "ok"}

Docker compose healthcheck config (in compose.yaml):

• Interval: 30s
• Timeout: 10s
• Retries: 3
• Start period: 10s

---

Local Development

Install Dependencies

uv sync

Run Locally

uv run python src/monarch_mcp_custom/server.py
# or
python -m monarch_mcp_custom.server

Test the Library Directly

uv run python -c "
from monarchmoney import MonarchMoney, MonarchMoneyEndpoints
print(MonarchMoneyEndpoints.BASE_URL)
"

---

Authentication Notes

Token Source

The MONARCH_TOKEN is a session token extracted from browser DevTools:

1. Log into Monarch Money at https://app.monarch.com
2. Open DevTools → Network → filter by graphql
3. Click any request → Headers → Authorization: Token <value>
4. Copy the token value (without Token prefix)

Token Lifetime

Tokens appear to last several months. If API calls start returning 401:

1. Extract a fresh token from the browser
2. Update the MONARCH_TOKEN env var in Komodo
3. Redeploy the stack

Re-Authentication Fallback

If token auth fails, the MCP server will attempt to re-authenticate using MONARCH_EMAIL, MONARCH_PASSWORD, and MONARCH_MFA_SECRET. This is subject to rate limiting by Monarch.

---

Troubleshooting

401 Unauthorized

• Token expired? Extract fresh token from browser.
• Check MONARCH_TOKEN is set correctly in Komodo stack env.
• Verify library version in startup logs (should show monarchmoney 1.3.2+ and BASE_URL: https://api.monarch.com).

429 Rate Limited

• Monarch Money rate-limits login attempts.
• Wait ~15-60 seconds before retrying.
• The retry decorator handles 429 with a 15s backoff.

Image Not Updating

• Check Gitea Actions for build failures.
• Force a Pull Stack in Komodo before deploying.
• Verify the commit hash in Komodo matches the latest.

Build Fails

• Check .gitea/workflows/build.yaml logs in Gitea.
• Ensure secrets.CR_PAT is valid for gitea.ext.ben.io.

---

Useful Commands

# Quick health check
curl -s http://localhost:8070/health | jq .

# Check running container
docker ps | grep monarch-mcp

# Inspect container logs directly on host
docker logs monarch-mcp-custom --tail 50 -f

# Restart container
docker restart monarch-mcp-custom

---

Related Resources

• Repo: git.local.ben.io:b3nw/monarch-mcp-custom.git
• Container Registry: gitea.ext.ben.io/b3nw/monarch-mcp-custom
• Komodo Stack: monarch-mcp (ID: 694b492b6e2254e6ad636e9b)
• Upstream Library: https://github.com/bradleyseanf/monarchmoneycommunity