mcpfire / docs

Developer Guide

Build, test, and troubleshoot MCP servers with production-ready examples.

Prerequisites

MCPFire account

REST API base URL

Must be reachable from this server

Auth credentials

API key, bearer token, or OAuth client

OpenAPI spec (optional)

Speeds up endpoint registration

Create Your First MCP Server

Navigate to Dashboard → MCP Registry → New Server and configure the following fields:

Field	Example	Notes
Server Name	`GitHub Integration`	Unique per workspace
Base URL	`https://api.github.com`	No trailing slash
Auth Type	`Bearer Token`	See Authentication tab
Description	`GitHub REST API v3`	Shown to AI as tool context

Register Tools (Endpoints)

Each registered endpoint becomes an MCP tool. Define path, method, and parameters:

json

{
  "name": "get_repository",
  "method": "GET",
  "path": "/repos/{owner}/{repo}",
  "description": "Fetch GitHub repository metadata",
  "parameters": [
    { "name": "owner", "type": "string", "required": true, "location": "path" },
    { "name": "repo",  "type": "string", "required": true, "location": "path" }
  ]
}

OpenAPI Import

Skip manual registration — paste your OpenAPI/Swagger spec URL under Import → OpenAPI Spec to auto-register all endpoints.

Test the Server

Once active, send a raw MCP tools/list request to verify tool registration:

bash

curl -X POST https://app.mcpgenai.com/mcp/{server-id} \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

Expected response:

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "get_repository",
        "description": "Fetch GitHub repository metadata",
        "inputSchema": {
          "type": "object",
          "properties": {
            "owner": { "type": "string" },
            "repo":  { "type": "string" }
          },
          "required": ["owner", "repo"]
        }
      }
    ]
  }
}

Verify Health Endpoint

bash

# Health check
curl https://app.mcpgenai.com/api/health

# Server-specific status
curl https://app.mcpgenai.com/api/bridges/{server-id}/status \
  -H "Authorization: Bearer <your-mcpfire-token>"

Server is healthy when

Status returns { "status": "running" } and tools/list returns at least one tool.

Best Practices

Production recommendations for stable, observable MCP servers.

Use HTTPS

All upstream API calls must use HTTPS in production. Plain HTTP is blocked by default.

Version your APIs

Include version prefix in base URL (e.g. /v2/). Pin to a stable version to avoid breaking changes.

Validate schemas

Test tool schemas with tools/list before connecting to AI clients. Use strict types.

Return proper status codes

200 for success, 400 for bad input, 401/403 for auth failures. Avoid returning 200 with error bodies.

Keep descriptions concise

Tool descriptions are sent to the AI model. Keep them under 100 characters. Be action-oriented.

Enable structured logging

Use JSON-formatted logs with request ID, latency, and status. Enables easier log aggregation.

Monitor latency & failures

Set alerts for p95 latency > 5s and error rate > 1%. MCPFire exports metrics via /api/metrics.

Rotate credentials

Rotate API keys and tokens every 90 days. Use environment variables — never hardcode secrets.