Key Takeaways
- MCP's JSON-RPC can't handle binary uploads, 270-tool servers bloat context, and rate limits fail silently.
- Use CLI scripts for files, allow-list tools, and prompt-based throttling.
What Changed — The specific update, with version/date if available
In late 2025, freee (Japan's dominant cloud accounting SaaS) shipped an MCP server. A developer immediately put it to work automating their entire kakutei shinkoku (self-employed tax return) with Claude Code. The results were impressive — 32 transactions categorized and written in three minutes instead of over an hour. But three production issues emerged that every Claude Code user should know about before connecting MCP to a real business process.
What It Means For You — Concrete impact on daily Claude Code usage
Break #1: No Binary Uploads via MCP
MCP's transport is JSON-RPC. It cannot send multipart/form-data. This means any workflow requiring file uploads — receipt images, PDFs, screenshots, binary assets — will fail at the protocol level.
Tool: mcp_server__api_post
Path: /api/v1/receipts
Body: { "company_id": "xxx", "description": "electric bill, July" }
Response: 400 — Content-Type must be "multipart/form-data"
This is not a freee bug. This is the shape of MCP itself.
Break #2: 270 Tools, Several Thousand Tokens Gone Before "Hello"
The freee MCP server exposes 270 tools — accounting, HR, invoicing, timekeeping. All 270 schemas load into every conversation turn. The developer only needed ~8 for a tax return. The other 262 sat in context, consuming tokens that could have been spent on transaction descriptions.
This is a real 2026 pattern: SaaS vendors ship "one MCP server for the whole product" instead of narrow, task-scoped servers. Connect two of these and you're spending most of the context window on tool descriptions before the model reads a single receipt.
Break #3: Rate Limits, Silently
freee's API rate-limits per minute. Batch-processing 32 transactions in a row hits it. With REST, you get a 429 with Retry-After. With MCP, the tool returns an error string. Claude sees a text failure and moves on. No backoff, no retry, no queue.
MCP has no rate-limit primitive in the protocol. There is no retry_after field for a tool response to signal "wait 30s then try me again."
Try It Now — Commands, config, or prompts to take advantage of this
Fix for Break #1: CLI Script for File Uploads
Don't fight MCP's protocol limitations. Create a separate Python script that hits the REST endpoint directly:
import requests
# Upload receipt via REST (not MCP)
response = requests.post(
"https://api.freee.co.jp/api/v1/receipts",
files={"file": open("receipt.pdf", "rb")},
headers={"Authorization": f"Bearer {token}"}
)
Then in your Claude Code prompt: "Use MCP for bookkeeping, then call my upload_receipt.py script for the file." Two tools, clean seam.
Fix for Break #2: Client-Side Tool Allow-Listing
Claude Desktop supports this via config. If your MCP client doesn't, you're stuck with the full 270. Check your client's documentation for tool allow-listing — it's the single biggest context-saving technique for large MCP servers.
Fix for Break #3: Prompt-Based Rate Limiting
Add to your prompt:
Write these transactions one at a time, waiting one second between each write.
Ugly, but it works. The 2026 story is that MCP gateways with per-tool token-bucket enforcement are starting to appear — that's where the fix eventually lives.
The Final Workflow
1. Import bank/card CSV → your script (not MCP)
2. Categorize + write transactions → MCP + Claude
3. Upload receipt PDFs → your script (not MCP)
4. Reconciliation & review → MCP + Claude
5. Final tax form generation → freee's own UI
MCP owns the parts where language understanding matters. The CLI owns the parts where MCP structurally cannot go — files, throttling, orchestration.
"MCP is a 90% automation layer, the last 10% is CLI glue" — and the last 10% is where all the design work is.
Source: dev.to
[Updated 28 Jul via devto_mcp]
The freee MCP server's 270-tool bloat isn't unique — developer Freema warns that every exposed tool is a tax on context, and recommends fewer, broader tools over many narrow ones. They also highlight MCP's readOnlyHint and destructiveHint annotations to help clients distinguish safe from unsafe calls, and suggest using resources (stable URIs) for reading instead of tools, which cost a definition on every request. These design patterns directly address the token-wasting issue that broke the tax return workflow.
