fyi-docs-mcp-ts

Remote MCP server for FYI Docs (document management system), built with Bun + TypeScript and deployed on Railway.

Exposes read-only FYI tools to MCP clients (Claude, Cursor, etc.) over Streamable HTTP for Somerset Accountancy Services.

Stack

Related MCP server: pontal-mcp

Tools

All tools are read-only in v1. Responses are summarised; secrets are redacted.

Endpoints

Environment variables

Required

FYI_ACCESS_ID=
FYI_ACCESS_SECRET=
FYI_REGION=uk
MCP_API_KEY=          # shared secret for /mcp (min 16 chars)

Optional

FYI_APPLICATION_ID=
FYI_API_USER=
FYI_BASE_URL=
PORT=3000
NODE_ENV=production

Override with FYI_BASE_URL if needed. Copy .env.example to .env for local development.

Local setup

bun install
cp .env.example .env   # fill in FYI credentials
bun run dev            # watch mode
# or
bun start

• Health: http://localhost:3000/health

• MCP: http://localhost:3000/mcp

Railway

This repo is connected to Railway. Deploys follow GitHub pushes.

Config is in railway.toml:

• Install: bun install --frozen-lockfile

• Start: bun run src/index.ts

• Health check: /health

Set secrets in Railway (do not commit them):

railway variables set FYI_ACCESS_ID=... FYI_ACCESS_SECRET=... FYI_REGION=uk MCP_API_KEY=...

Optional Dockerfile (oven/bun:1) is included if you prefer image-based builds.

Authentication (API key only)

No OAuth. /mcp requires the shared MCP_API_KEY via header:

• Authorization: Bearer <MCP_API_KEY>

• or x-api-key: <MCP_API_KEY>

/health stays public for Railway health checks.

{
  "mcpServers": {
    "fyi-docs": {
      "url": "https://fyi-mcp-production.up.railway.app/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_API_KEY>"
      }
    }
  }
}

Grok Build / CLI:

[mcp_servers.fyi-docs]
url = "https://fyi-mcp-production.up.railway.app/mcp"
headers = { "Authorization" = "Bearer <MCP_API_KEY>" }

Note: Hosts that only support OAuth custom connectors (e.g. Grok.com web) cannot connect to this server. Use clients that accept a static Authorization header.

Scripts

Project layout

src/
  index.ts           # Bun HTTP entry (/health, /mcp)
  server.ts          # MCP server + tool registration
  fyi/
    client.ts        # FYI External API client
    config.ts        # Env validation (Zod)
    types.ts
  tools/
    documents.ts
    clients.ts
    jobs.ts
    tasks.ts
    cabinets.ts
    connection.ts
  utils/
    response.ts      # Summaries + safe errors

Security

• No secrets in source or logs

• Fail-fast on missing FYI_ACCESS_ID / FYI_ACCESS_SECRET / MCP_API_KEY

• /mcp protected by shared API key only (no OAuth)

• Read-only tools for v1

• Sensitive keys redacted from tool output

Out of scope (v1)

OAuth, write/upsert operations, binary document download, custom domain, persistent storage.

License

Private / unlicensed unless stated otherwise.