Model Context Protocol (MCP) Server
Relevant source files
The following files were used as context for generating this wiki page:
The Model Context Protocol (MCP) Server in Syllogic is a dedicated service designed to provide LLMs (like Claude Desktop) and other programmatic clients with structured, context-aware access to financial data. It acts as a bridge between the application's PostgreSQL database and AI agents, enabling them to query accounts, transactions, and analytics through a standardized protocol.
The server primarily provides read-only access to help the AI understand the user's financial state, though it supports specific write operations such as updating transaction categories to improve data organization.
Sources: backend/app/mcp/init.py:1-6, deploy/compose/README.md:52-54
Architecture and Deployment
The MCP server is implemented as a FastMCP HTTP server. It is built using the same base Python image as the backend API and worker services but runs as a distinct process type.
Deployment configuration
The service is integrated into all standard deployment paths, including Docker Compose, Railway, and CasaOS. It shares the same PostgreSQL database as the primary application to ensure data consistency.
The diagram shows how external AI clients interact with the MCP server, which in turn queries the shared PostgreSQL database.
Sources: deploy/compose/docker-compose.yml:76-85, deploy/railway/docker-compose.yml:64-73, deploy/compose/README.md:56-58
Configuration Parameters
| Parameter | Default Value | Description |
|---|---|---|
PROCESS_TYPE | mcp | Identifies the container role in the backend image. |
PORT | 8001 | The internal container port for the MCP service. |
MCP_PORT | 8001 | The external host port (configurable via environment variables). |
DATABASE_URL | (Required) | PostgreSQL connection string used to retrieve financial data. |
OPENAI_API_KEY | (Optional) | Enables AI-specific features within the MCP context. |
Sources: deploy/compose/docker-compose.yml:86-102, deploy/compose/README.md:68-71
Available Tools
The MCP Server exposes several tool categories that allow AI models to interact with specific domains of the personal finance application.
Financial Data Tools
These tools provide the core data required for an LLM to understand a user's financial position.
- Accounts: Tools for listing accounts, retrieving specific account details, and viewing balance history.
- Categories: Tools to manage the category hierarchy, including listing all categories and retrieving the category tree.
- Transactions: Extensive tools for listing, searching, and getting details for specific transactions.
Analytics and Recurring Payments
Beyond raw data, the server provides processed insights to help models perform financial analysis.
- Analytics: Includes tools for spending/income breakdown by category, monthly cashflow analysis, financial summaries, and merchant identification.
- Recurring: Tools for monitoring subscriptions and recurring transaction patterns.
Write Operations
While the protocol is largely read-oriented, it includes the update_transaction_category tool, which is the only write operation currently supported.
Sources: backend/app/mcp/init.py:12-40
Security and Authentication
Access to the MCP server is secured via Bearer token authentication. Users must generate an API key within the Syllogic Web UI (Settings -> API Keys) to authorize their MCP clients.
Sequence diagram illustrating the authentication flow and tool execution process.
Summary
The Model Context Protocol (MCP) Server is a critical component for the "AI-powered" nature of the Syllogic platform. By exposing a FastMCP interface on port 8001, it allows users to bring their own AI agents to interact directly with their financial data in a secure and structured manner. This modular approach separates the core data processing from the interaction layer, enabling complex financial queries and categorization updates through natural language interfaces.
Sources: backend/app/mcp/init.py:1-40, README.md:15-18