LKPlanWise MCP Server

Stateless MCP adapter for the LKPlanWise Go REST API. AI clients call curated MCP tools over Streamable HTTP; this service validates tool contracts and forwards each caller's Bearer credential to the Go backend. It does not connect to PostgreSQL or duplicate financial business rules.

Architecture

AI Agent
  -> MCP Streamable HTTP
  -> Python FastMCP server
  -> HTTPX + request-scoped Bearer credential
  -> LKPlanWise Go API
  -> service layer
  -> PostgreSQL

Requirements

• Python 3.12+
• uv
• Running LKPlanWise Go backend

Setup

uv python install 3.12
uv sync
Copy-Item .env.example .env

Configure LKPLANWISE_MCP_BACKEND_BASE_URL in .env, then run:

uv run lkplanwise-mcp-server

The MCP endpoint is available at:

http://127.0.0.1:8000/mcp

The operational health endpoint is:

http://127.0.0.1:8000/healthz

First tool

list_financial_accounts lists accounts owned by the authenticated user. The MCP request must include:

Authorization: Bearer <credential>

The credential is forwarded to GET /financial-accounts on the Go backend. The Go backend remains responsible for validating the credential, resolving the user, enforcing ownership, and applying business rules.

The current Go middleware accepts JWT access tokens. Before using sk-lk-* Agent API keys end to end, add a restricted Agent-authenticated route group to the Go backend or extend only the intended resource routes with Agent API key authentication.

Development

uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run mypy

Test the running server with MCP Inspector:

npx -y @modelcontextprotocol/inspector

Connect the Inspector to http://127.0.0.1:8000/mcp and provide the Authorization header in its connection settings.

Design rules

• Tools are curated user actions, not an automatic mirror of REST endpoints.
• The MCP service never connects directly to the database.
• Credentials are request-scoped and must never be logged or returned.
• Reads and writes are separate tools with accurate safety annotations.
• Consequential write tools require idempotency support in the Go backend.