formbro-mcp-server

FormBro MCP Server

MCP server for FormBro Canadian immigration application automation. It provides agent access to FormBro applications, applicants, employers, validation, export, and controlled write workflows through the Model Context Protocol.

Features

• Hosted MCP - Use https://mcp.formbro.ca/mcp from Claude Code, Codex, Cursor, and other MCP clients.
• Local stdio MCP - Use npx -y formbro-mcp-server for Claude Desktop and offline debugging.
• Toolset gating - Public default is system,read,validate; write/export/audit tools require explicit opt-in.
• Secure authentication - Token-based FormBro API authentication with per-request bearer tokens for hosted HTTP.
• Dual transport - Supports stdio (local) and Streamable HTTP (hosted/self-hosted) modes.

Hosted MCP Quick Start

claude mcp add --transport http formbro \
  "https://mcp.formbro.ca/mcp?toolsets=system,read,validate" \
  --header "Authorization: Bearer fb_your_token_here"

For Codex:

export FORMBRO_API_TOKEN=fb_your_token_here
codex mcp add formbro \
  --url "https://mcp.formbro.ca/mcp?toolsets=system,read,validate" \
  --bearer-token-env-var FORMBRO_API_TOKEN

Use local stdio only when your client requires a local MCP process or you need offline debugging.

Installation

Option 1: Using npx

No installation needed - run directly:

npx -y formbro-mcp-server --toolsets=system,read,validate

Option 2: Global Installation

npm install -g formbro-mcp-server

Option 3: Local Installation

npm install formbro-mcp-server

Quick Start

Get Your API Token

• Log in to FormBro
• Navigate to Settings > API Tokens
• Generate a new token (starts with fb_)

Run the Server

stdio mode (for Claude Desktop)

FORMBRO_API_URL=https://backend.formbro.ca \
FORMBRO_API_TOKEN=fb_your_token_here \
formbro-mcp-server --toolsets=system,read,validate

HTTP mode (for remote access / Claude Code HTTP)

FORMBRO_API_URL=https://backend.formbro.ca \
TRANSPORT=http \
PORT=3000 \
formbro-mcp-server --toolsets=system,read,validate

Note: In HTTP mode, the token is provided per-request via the Authorization header, not in the environment.

Configuration

Environment Variables

Variable	Required	Mode	Description	Default
FORMBRO_API_URL	✅ Yes	Both	Base URL of FormBro API	-
FORMBRO_API_TOKEN	✅ Yes	stdio only	API token for authentication	-
TRANSPORT	No	Both	Transport mode: stdio or http	stdio
PORT or MCP_PORT	No	HTTP only	HTTP server port	3000

Connecting to Claude

Claude Desktop Configuration

Claude Desktop uses stdio transport for local process communication.

Method 1: Using npx (Recommended)

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "formbro": {
      "command": "npx",
      "args": ["-y", "formbro-mcp-server"],
      "env": {
        "FORMBRO_API_URL": "https://backend.formbro.ca",
        "FORMBRO_API_TOKEN": "fb_your_token_here"
      }
    }
  }
}

Method 2: Using global installation

{
  "mcpServers": {
    "formbro": {
      "command": "formbro-mcp-server",
      "env": {
        "FORMBRO_API_URL": "https://backend.formbro.ca",
        "FORMBRO_API_TOKEN": "fb_your_token_here"
      }
    }
  }
}

Method 3: Using local Node.js

{
  "mcpServers": {
    "formbro": {
      "command": "node",
      "args": ["/path/to/formbro-mcp-server/dist/index.js"],
      "env": {
        "FORMBRO_API_URL": "https://backend.formbro.ca",
        "FORMBRO_API_TOKEN": "fb_your_token_here"
      }
    }
  }
}

Restart Claude Desktop after updating the configuration.

Claude Code Configuration

Claude Code supports both stdio and HTTP transports.

Method 1: HTTP Transport (Recommended for Claude Code)

Step 1: Start the HTTP server

# In a terminal, run:
FORMBRO_API_URL=https://backend.formbro.ca \
TRANSPORT=http \
PORT=3000 \
formbro-mcp-server

Or create an .env file:

# .env
FORMBRO_API_URL=https://backend.formbro.ca
TRANSPORT=http
MCP_PORT=3000

Then run:

formbro-mcp-server

Step 2: Add to Claude Code with your token

# Option A: Using Bearer token format
claude mcp add --transport http formbro http://localhost:3000/mcp \
  --header "Authorization: Bearer fb_your_token_here"

# Option B: Direct token format (also supported)
claude mcp add --transport http formbro http://localhost:3000/mcp \
  --header "Authorization: fb_your_token_here"

Verify connection:

claude mcp list

Method 2: stdio Transport

claude mcp add --transport stdio formbro -- \
  env FORMBRO_API_URL=https://backend.formbro.ca \
  FORMBRO_API_TOKEN=fb_your_token_here \
  npx -y formbro-mcp-server

Method 3: stdio with global installation

claude mcp add --transport stdio formbro -- \
  env FORMBRO_API_URL=https://backend.formbro.ca \
  FORMBRO_API_TOKEN=fb_your_token_here \
  formbro-mcp-server

Managing MCP Servers in Claude Code

# List all MCP servers
claude mcp list

# Remove a server
claude mcp remove formbro

# Update server configuration
claude mcp remove formbro
claude mcp add --transport http formbro http://localhost:3000/mcp \
  --header "Authorization: Bearer fb_new_token"

Available Tools

formbro_find ⭐ (Recommended)

Smart search across all entity types with intelligent name matching.

Why use this first?

• Combines search and detail fetching in one call
• Handles "First Last" and "Last First" name order automatically
• Returns compact JSON optimized for AI processing
• Can include related applications in the same response

Examples:

// Find applicant by name
formbro_find({ name: "Zhang Wei" })

// Find with applications included
formbro_find({ name: "John Smith", include: ["applications"] })

// Filter by program
formbro_find({ name: "Wei", program: "tr", include: ["applications"] })

// Limit results
formbro_find({ name: "Smith", limit: 10 })

Parameters:

• name (required): Name to search for. Supports full name in any order.
• program (optional): Filter by "tr", "pr", or "lmia"
• include (optional): Array of ["applications"] or ["applications", "employer"]
• limit (optional): Maximum results to return (1-20, default: 5)

formbro_list_applicants

List applicants with search, program filtering, and pagination.

Parameters:

• limit (optional): Maximum results to return (1-100, default: 20)
• offset (optional): Number of results to skip for pagination (default: 0)
• search (optional): Search query to filter by name, email, etc.
• program (optional): Filter by program type ("tr", "pr", "lmia")
• response_format (optional): "markdown" or "json" (default: "markdown")

formbro_get_applicant

Get detailed applicant information by ID.

Parameters:

• id (required): The applicant's unique identifier (MongoDB ObjectId)
• response_format (optional): "markdown" or "json" (default: "markdown")

formbro_list_applications

List applications by program type with status filtering.

Programs:

• tr - Temporary Residence (Work permits, study permits, visitor visas)
• pr - Permanent Residence (Family sponsorship, Express Entry, PNP)
• lmia - Labour Market Impact Assessment (Employer applications)

Parameters:

• limit (optional): Maximum results to return (1-100, default: 20)
• offset (optional): Number of results to skip for pagination (default: 0)
• search (optional): Search query to filter by case name
• program (optional): Filter by program type ("tr", "pr", "lmia")
• status (optional): Filter by status ("draft", "in_progress", "submitted", "approved", "refused")
• response_format (optional): "markdown" or "json" (default: "markdown")

formbro_get_application

Get detailed application information by ID.

Parameters:

• id (required): The application's unique identifier (MongoDB ObjectId)
• response_format (optional): "markdown" or "json" (default: "markdown")

formbro_list_employers

List employers with search and pagination.

Parameters:

• limit (optional): Maximum results to return (1-100, default: 20)
• offset (optional): Number of results to skip for pagination (default: 0)
• search (optional): Search query to filter by company name, business number, etc.
• response_format (optional): "markdown" or "json" (default: "markdown")

formbro_get_employer

Get detailed employer information by ID.

Parameters:

• id (required): The employer's unique identifier (MongoDB ObjectId)
• response_format (optional): "markdown" or "json" (default: "markdown")

API Response Formats

All tools support two response formats:

• markdown (default) - Human-readable formatted output for Claude
• json - Machine-readable structured data

HTTP API Endpoints

When running in HTTP mode, the server exposes:

GET /health

Health check endpoint returning server status.

Response:

{
  "status": "ok",
  "server": "formbro-mcp-server",
  "version": "1.0.0",
  "apiUrl": "https://backend.formbro.ca",
  "apiConfigured": true
}

POST /mcp

Main MCP endpoint using Streamable HTTP transport.

Headers:

Authorization: Bearer fb_your_token_here
Content-Type: application/json

Request Body: MCP protocol JSON-RPC message

GET /mcp

Returns server information and available tools.

Troubleshooting

Claude Desktop Issues

Server not connecting:

• Check the config file location is correct for your OS
• Verify JSON syntax (use a JSON validator)
• Ensure the token starts with fb_
• Restart Claude Desktop after config changes
• Check Claude Desktop logs: ~/Library/Logs/Claude/ (macOS)

Token errors:

• Generate a new token from FormBro Settings
• Ensure no extra spaces in the token
• Token should start with fb_

Claude Code Issues

HTTP connection failed:

• Ensure the server is running (curl http://localhost:3000/health)
• Check the port is not in use by another service
• Verify the Authorization header format
• Test with curl:

  curl -X POST http://localhost:3000/mcp \
    -H "Authorization: Bearer fb_your_token" \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
  

stdio connection failed:

• Check if npx or formbro-mcp-server is in PATH
• Verify environment variables are set correctly
• Test manually:

  FORMBRO_API_URL=https://backend.formbro.ca \
  FORMBRO_API_TOKEN=fb_your_token \
  formbro-mcp-server
  

Development

Setup

# Clone the repository
git clone https://github.com/jackyzhang69/formbro.git
cd formbro/mcp-server

# Install dependencies
pnpm install

# Build
pnpm build

# Run in development mode
pnpm dev

Testing

# Test stdio mode
FORMBRO_API_URL=https://backend.formbro.ca \
FORMBRO_API_TOKEN=fb_your_token \
pnpm start

# Test HTTP mode
FORMBRO_API_URL=https://backend.formbro.ca \
TRANSPORT=http \
PORT=3000 \
pnpm start

# Test health endpoint
curl http://localhost:3000/health

# Test MCP endpoint
curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer fb_your_token" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Project Structure

mcp-server/
├── src/
│   ├── index.ts              # Main entry point, transport setup
│   ├── services/
│   │   └── api-client.ts     # FormBro API client
│   └── tools/
│       ├── find.ts           # Smart find tool
│       ├── applicants.ts     # Applicant tools
│       ├── applications.ts   # Application tools
│       └── employers.ts      # Employer tools
├── dist/                     # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md

Security Notes

• Token Security: Never commit API tokens to version control
• HTTP Mode: Uses per-request authentication via Authorization header
• stdio Mode: Token is passed via environment variables (process-scoped)
• Production: Use HTTPS for HTTP transport in production environments
• Token Format: All FormBro API tokens start with fb_

License

MIT

Links

• FormBro
• Model Context Protocol
• npm Package
• GitHub Repository

Support

For issues and questions:

• GitHub Issues: https://github.com/jackyzhang69/formbro/issues
• FormBro Support: [e-mail]