Aframe MCP Connector

A Node.js MCP server that bridges Claude sessions to the Aframe Open API. Deployed on Railway, exposed to Claude.ai as a custom remote MCP connector.

Status

v0.2.0 — POC validated, expanded to core transaction CRUD + custom fields.

Tools

Related MCP server: freee MCP Server

Architecture

Claude.ai session
  ↓  (custom MCP connector — Streamable HTTP)
Railway service (this repo)
  ↓  (HTTPS with X-AFrame-API-Key header)
Aframe Open API

Local development

1. npm install

2. Copy .env.example to .env and fill in AFRAME_API_KEY

3. npm start

4. Verify health: curl http://localhost:3000/ → {"status":"ok",...}

Deployment (Railway)

Auto-deploys on push to main. Required environment variable:

• AFRAME_API_KEY — your Aframe API key

Generate a public domain under Settings → Networking after the first deploy.

Connecting to Claude.ai

Settings → Connectors → Add custom connector → paste https://<railway-url>/mcp → Add.

Tools become available in any new conversation with the connector enabled.

Implementation notes

Aframe response envelope: { payload, error }. The error block can appear alongside payload on 2xx success responses (as validation warnings, e.g. "defaulted to current AppUser"). HTTP status is the authoritative success/failure signal — error on 2xx is surfaced as warnings, not thrown.

JSON Patch (RFC 6902): Aframe's PATCH endpoints (update_transaction, update_custom_field) require an array of patch operations with Content-Type: application/json-patch+json. The MCP tools accept friendly flat-object inputs (e.g. { closingDate: "2026-08-15" }) and the client internally constructs the patch array. Callers never need to write RFC 6902 syntax.

Custom fields: Stored as a flat xactionFieldData map keyed by Merge Field Code (e.g. f_EarnestMoney). All values are strings regardless of underlying type — Aframe handles type coercion server-side.

Auth note

This service runs authless. Acceptable for development since the Railway subdomain is effectively unguessable, but not suitable for production. Claude.ai's custom connector UI does not currently support pasted bearer tokens (per the connector auth docs); production use will require OAuth 2.1 with PKCE.

Version history

• v0.2.0 — Added get_transaction, update_transaction, update_custom_field. Fixed response envelope parsing to treat error on 2xx as warnings rather than failures. JSON Patch helper for PATCH endpoints.

• v0.1.0 — Initial POC with create_transaction and add_transaction_note.

Reference

• Aframe Open API: https://api.aframeonline.com/api-pub/swagger-ui/index.html

• MCP spec: https://modelcontextprotocol.io

• Claude custom connectors: https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp

• JSON Patch (RFC 6902): https://datatracker.ietf.org/doc/html/rfc6902