FINANCE API IMPLEMENTATION GUIDE
MCP finance tools: designing safe API capabilities for AI agents
A practical pattern for exposing finance controls through MCP without duplicating business logic or delegating consequential authority.
Expose bounded tools, not an opaque finance agent
A tool should describe one operation with explicit inputs, outputs, cost, latency, and consequences. Names such as validate_invoice and get_invoice_exceptions are easier to select and compose than perform_finance_task. The external agent decides when to call; the service performs a narrow control.
- Use strict JSON Schema inputs.
- Publish structured outputs, not prose-only content.
- Name read-only boundaries in descriptions.
- Return agent-readable errors with a safe next action.
Proxy the REST API
The MCP adapter should call the same REST routes customers use directly. Duplicating normalization or duplicate rules inside the MCP server creates contract drift and two audit paths. A thin adapter also lets REST and MCP share tenant isolation, idempotency, rate limits, usage metering, and error behavior.
Authenticate every tool call
Initialization and tool discovery can be public, but execution should require an organization-scoped key. Never accept tenant IDs from model-generated arguments. Resolve the tenant from the verified credential and enforce scopes on the server.
Treat tool descriptions as guidance, not security controls. A client can call a tool directly, so authorization and validation must remain inside the API.
Keep consequential actions downstream
Finance tools can return a CLEAR control result, but they should not approve an invoice, choose a vendor, create a bill, or initiate payment. If a customer later connects a write-capable tool, require separate credentials and an explicit customer approval policy around that action.
REPRESENTATIVE CONTRACT
Remote MCP tool call
The values below are synthetic. Use a tenant-scoped key stored as a secret, and evaluate the documented status, decision, evidence, and next action before continuing a workflow.
POST /mcp
Authorization: Bearer apc_...
Content-Type: application/json
{
"jsonrpc": "2.0",
"id": "validate-1042",
"method": "tools/call",
"params": {
"name": "validate_invoice",
"arguments": {
"invoice": {
"vendor_name": "Northstar Supply",
"invoice_number": "INV-1042",
"currency": "USD",
"total": "1250.00"
}
}
}
}{
"jsonrpc": "2.0",
"id": "validate-1042",
"result": {
"structuredContent": {
"status": "COMPLETED",
"decision": "CLEAR",
"exceptions": [],
"next_action": "Send the invoice to AP Control for duplicate analysis."
}
}
}IMPLEMENTATION CHECKLIST
Ship the control with its safety boundary intact.
- Expose atomic tool names.
- Provide input and output schemas.
- Proxy one REST implementation.
- Resolve tenants from credentials.
- Require explicit scopes.
- Keep ERP and payment writes in separately authorized tools.
FREQUENTLY ASKED QUESTIONS
Questions workflow builders ask
Should MCP tool discovery require an API key?
It may be public when schemas reveal no customer data, but every actual tool invocation should require an authenticated tenant-scoped credential.
Why proxy REST instead of implementing rules in MCP?
One business-logic path prevents behavior drift and lets all interfaces share security, audit, idempotency, and tests.
Does a CLEAR tool result authorize an agent to act?
No. It is control evidence for the customer's separate approval and authorization process.