Exosphere MCP Factory

What the Factory Does

The Exosphere MCP Factory is a web service and API that generates complete, deployable MCP (Model Context Protocol) server packages from an Estate Manifest JSON file. You provide a JSON description of your BSS estate; the factory returns a ready-to-deploy TypeScript/Node.js MCP server in under 50ms.

The Pipeline in One Sentence

You describe your BSS estate in JSON. The factory turns that description into working code. You deploy the code. AI agents can now query your BSS systems in plain language.

What is an MCP Server?

An MCP server is the bridge between an AI agent — Claude, GPT-4o, Azure Copilot, Dify, or any LLM with tool-use capability — and your BSS systems. The AI agent calls MCP tools by name: show-latest-bill, get-products, check-order-status. The MCP server translates those calls into real API requests to your billing system, product catalogue, order management platform, or CRM — and returns structured data the AI can reason about.

Without an MCP server, an AI agent cannot act on live BSS data. It can only reason about static information in its training corpus or in documents you paste into the prompt. With an MCP server, the agent has live, authoritative access to customer accounts, invoices, service orders, and support tickets — in real time, on every query.

What the Factory Generates

Given an Estate Manifest, the factory produces a complete Node.js package containing all of the following:

• A TypeScript MCP server entry point with all registered tool handlers
• One BSS adapter file per enabled adapter (billing, product, order, care)
• Typed field maps and status maps baked in as TypeScript constants
• Zod schema validation for every tool's input parameters
• Static BSS client libraries with authentication wired up
• A .env.example file listing all required environment variables
• A Dockerfile for containerised deployment
• A README.md with setup and run instructions
• A package.json with all dependencies declared

No code generation AI is involved — the factory uses a deterministic template engine. The output is always predictable, auditable, and reproducible from the same manifest. You can version-control the manifest and regenerate the server at any time.

Where the Factory Fits (Cartographer → Factory Pipeline)

The Factory is Stage B of the Exosphere Agentic BSS pipeline. Stage A — the Cartographer — is an AI agent that analyses a live BSS estate and automatically produces an Estate Manifest. Stage B — the Factory — takes that manifest and generates the MCP server.

You can use the Factory standalone today: write a manifest by hand (or start from the provided examples) and generate the server immediately. When the Cartographer is available, the two stages will be chainable: point the Cartographer at your BSS, receive a manifest, feed it to the Factory, and receive a deployable MCP server — with no manual authoring required.

Quick Start

From zero to a deployable MCP server in three steps. No local tooling required for steps 1–3 — everything runs in the browser.

Estate Manifest Reference

The Estate Manifest is a JSON document that describes your BSS estate — which systems you operate, how to authenticate with them, what data fields they expose, and which MCP tools to enable. It is the single input to the Factory.

Below is a complete annotated manifest showing all supported fields. Fields shown with { ... } follow the same structure as the preceding adapter — see Section 4 for per-adapter details.

{
  "manifest_version": "1.0",

  "customer": {
    "name":   "Your Telecom Name",
    "id":     "your-telecom-id",
    "region": "caribbean"
  },

  "adapters": {

    "billing": {
      "type":     "fossbilling",
      "base_url": "https://your-fossbilling.example.com",
      "auth": {
        "type":    "token",
        "env_var": "FOSSBILLING_TOKEN"
      },
      "capabilities": {
        "invoices": {
          "field_map": {
            "total":        "totalAmount",
            "nr":           "invoiceNumber",
            "date_created": "issueDate",
            "due_date":     "dueDate",
            "status":       "status",
            "currency":     "currency"
          },
          "status_map": {
            "paid":      "settled",
            "unpaid":    "new",
            "refunded":  "disputed",
            "cancelled": "onHold"
          }
        }
      }
    },

    "product": {
      "type":     "product-catalog",
      "base_url": "https://your-product-catalog.example.com",
      "auth": {
        "type":    "token",
        "env_var": "PRODUCT_CATALOG_TOKEN"
      },
      "capabilities": {
        "products": {
          "field_map": {
            "id":        "productId",
            "title":     "productName",
            "price":     "monthlyPrice",
            "is_active": "available"
          }
        }
      }
    },

    "order": {
      "type":     "order-management",
      "base_url": "https://your-orders.example.com",
      "auth": {
        "type":    "token",
        "env_var": "ORDER_MGMT_TOKEN"
      }
    },

    "care": {
      "type":     "suitecrm",
      "base_url": "https://crm.your-telecom.example.com",
      "auth": {
        "type":       "oauth2",
        "client_id": "your-oauth2-client-id",
        "env_var":   "SUITECRM_CLIENT_SECRET"
      }
    }

  },

  "tools": {
    "enabled": [
      "show-latest-bill",
      "compare-latest-bill",
      "place-a-new-order",
      "get-products",
      "check-order-status",
      "get-open-tickets"
    ]
  }

}

Field Reference: Top-Level Sections

Field Reference: Adapter Object

Supported Adapters

An adapter is a generated module that handles all communication with one BSS system type. The factory currently supports four adapter types, covering the core BSS estate of a typical telecoms operator.

Adapter Dependencies

Adapters are only generated if at least one tool in tools.enabled requires that adapter. If you enable only billing tools, only the billing adapter file is generated — product, order, and care files are not included in the ZIP. This keeps the generated package minimal and avoids unused dependencies.

The inverse also applies: if you declare an adapter in the manifest but enable no tools for it, that adapter is silently omitted. There are no empty adapter files in the output.

Available Tools

The factory supports 13 MCP tools across the four adapter types. Each tool is independently enableable via tools.enabled in the manifest. You can enable any subset — from a single tool up to all 13.

Tool-to-Adapter Mapping

Disabling all tools for a given adapter removes that adapter's generated files entirely. For example: if you enable only show-latest-bill and get-open-tickets, the factory generates only the billing adapter and the care adapter — no product or order files are created, and those BSS credentials are not required in .env.

Field Maps and Status Maps

BSS systems speak their own language. Your billing system calls a field nr; your AI agent should see invoiceNumber. The manifest's field and status maps handle this translation at generation time — not at runtime.

Field Maps

A field_map is a simple object where each key is a BSS API field name and each value is the clean, semantic name that will appear in the MCP tool response. The factory bakes this map directly into the generated TypeScript as a typed constant — there is no runtime lookup, no external configuration, and no performance overhead.

In the generated TypeScript, the field map appears as a constant that the adapter applies to every API response before returning it to the MCP tool handler:

// Auto-generated by Exosphere MCP Factory v1.0.0
// DO NOT EDIT — regenerate from manifest to update

export const INVOICE_FIELD_MAP: Record<string, string> = {
  nr:           'invoiceNumber',
  total:        'totalAmount',
  date_created: 'issueDate',
  due_date:     'dueDate',
  status:       'status',
  currency:     'currency',
};

export function applyFieldMap(
  raw: Record<string, unknown>,
  map: Record<string, string>
): Record<string, unknown> {
  const result: Record<string, unknown> = {};
  for (const [rawKey, rawVal] of Object.entries(raw)) {
    const mappedKey = map[rawKey] ?? rawKey;
    result[mappedKey] = rawVal;
  }
  return result;
}

Status Maps

A status_map translates BSS-internal status codes into semantic values that an AI agent can reason about and communicate naturally to an end user. BSS systems often use terse or legacy status codes that are perfectly clear to a billing engineer but ambiguous for an LLM generating a natural-language response.

Like field maps, the status map is baked into the generated TypeScript at factory time. The generated server does not call back to the factory at runtime — all mappings are static constants in the adapter file.

API Reference

The factory exposes a simple REST API. All endpoints except /health require HTTP Basic Auth. The UI is a wrapper around the same API — all operations can be performed programmatically.

{
  "status":  "ok",
  "service": "exosphere-mcp-factory",
  "version": "1.0.0"
}

[
  {
    "id":           "fossbilling-demo",
    "name":         "FOSSbilling Demo",
    "description":  "Caribbean telecoms, FOSSbilling + SuiteCRM",
    "toolCount":    6,
    "adapterCount": 3
  }
]

{
  "success":      true,
  "toolCount":    6,
  "adapterCount": 3,
  "fileCount":    11,
  "durationMs":   42,
  "files": [
    { "path": "src/index.ts",           "size": 2841 },
    { "path": "src/adapters/billing.ts", "size": 4312 },
    { "path": "src/adapters/product.ts", "size": 3218 },
    { "path": "src/adapters/care.ts",    "size": 3904 },
    { "path": "package.json",           "size":  712 },
    { "path": ".env.example",           "size":  248 },
    { "path": "Dockerfile",             "size":  580 },
    { "path": "README.md",              "size": 1640 }
  ],
  "downloadUrl": "/download/mcp-server-your-telecom-id.zip"
}

{
  "error":   "Manifest validation failed",
  "details": [
    "manifest_version is required",
    "tools.enabled must contain at least one tool name"
  ]
}

Example: cURL

# Download the example manifest, pipe it straight to /generate, save as ZIP
curl -u "user:pass" https://factory.exos.bluenotelogic.com/examples/fossbilling-demo \
  | curl -u "user:pass" -X POST \
      -H "Content-Type: application/json" \
      -d @- \
      https://factory.exos.bluenotelogic.com/generate \
      -o mcp-server.zip

# Or generate from your own manifest file
curl -X POST https://factory.exos.bluenotelogic.com/generate \
  -u "user:pass" \
  -H "Content-Type: application/json" \
  -d @my-estate-manifest.json \
  -o mcp-server.zip

Deploying the Generated Server

The generated MCP server is a standard Node.js/TypeScript package. It runs anywhere Node.js runs: bare metal, VPS, Docker, or Kubernetes. Typical first deployment takes under 10 minutes.

Node.js Deployment

Docker Deployment

A Dockerfile is included in every generated package. It uses a Node.js 18 Alpine base image and produces a minimal production image.

# Build the image
docker build -t my-mcp-server .

# Run with env file
docker run -d \
  -p 3000:3000 \
  --env-file .env \
  --name my-mcp-server \
  my-mcp-server

# Check logs
docker logs -f my-mcp-server

# Health check
curl http://localhost:3000/health

AI Agent Integration

Troubleshooting

Most issues fall into three categories: manifest validation errors (before generation), deployment errors (after downloading the ZIP), and runtime connectivity errors (once the server is running). This section covers the most common cases in each category.

Factory Errors (During Generation)

Deployment Errors (Post-Generation)

Runtime Errors (BSS Connectivity)