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

Component	Choice
Runtime	Bun
Language	TypeScript (strict)
MCP SDK	`@modelcontextprotocol/sdk`
Transport	Streamable HTTP (Web Standard, Bun-native)
Validation	Zod
Hosting	Railway (GitHub-connected)

Tools

Tool	Description
`search_documents`	Search/list documents
`search_clients`	Search/list clients (`/entity`)
`list_jobs`	List jobs
`list_tasks`	List tasks
`list_cabinets`	List filing cabinets
`fyi_raw_list`	Low-level list against any FYI resource
`check_fyi_connection`	Verify credentials / connectivity

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

Endpoints

Path	Purpose
`GET /health`	Railway health check (200)
`ALL /mcp`	MCP Streamable HTTP endpoint
`GET /`	Service metadata

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

`FYI_REGION`	Base URL
`uk`	`https://api-eu-west-2.fyi.app/external`
`au` / `anz`	`https://api-ap-southeast-2.fyi.app/external`

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

Script	Command
`bun start`	Run server
`bun run dev`	Run with `--watch`
`bun run typecheck`	`tsc --noEmit`
`bun run build`	Bundle to `dist/`

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.