DiffBeam MCP and OpenAPI contracts

MCP endpoint

The remote MCP endpoint is https://api.gaussian-beam.com/mcp/. It uses Streamable HTTP and exposes public optics tools plus capability-bound workspace tools. Public validation, simulation, catalog search, and schema resources do not require workspace authority. Write-capable workspace tools require a workspace_credential tool argument and expected revision checks.

• validate_optical_system and get_optical_system_schema are schema and authoring checks.
• simulate_optical_system is deterministic and does not modify user workspaces.
• search_fibers, search_fiber_collimators, and search_lenses query local catalogs.
• create_design_link stores an immutable public design link with no edit authority.

Direct Agent Bridge

Agents that can make HTTPS POST requests but do not support native MCP can use the workspace-specific endpoint https://api.gaussian-beam.com/api/agent/workspaces/{public_workspace_id}. The planner's Connect your AI dialog creates a temporary scoped credential and places it into a ready-to-copy prompt. This route is not an anonymous public write API.

Commands are discriminated by operation: get_workspace, preview_workspace_design, apply_workspace_design, list_workspace_revisions, and restore_workspace_revision. Credentials stay in the JSON body. Payloads are bounded, unexpected fields are rejected, responses are non-cacheable, and writes require the latest expected revision. See the complete agent-facing bridge guide.

Registry metadata

The public manifest for registry and client discovery is https://gaussian-beam.com/.well-known/mcp/server.json. It uses the official MCP Registry 2025-12-11 schema URI, the server name com.gaussian-beam/diffbeam, version 1.0.0, and one Streamable HTTP remote. It intentionally declares no HTTP headers because workspace credentials are issued by the planner and passed only as MCP tool arguments.

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "com.gaussian-beam/diffbeam",
  "title": "DiffBeam Gaussian Beam Optics",
  "version": "1.0.0",
  "remotes": [
    {
      "type": "streamable-http",
      "url": "https://api.gaussian-beam.com/mcp/"
    }
  ]
}

Public HTTP APIs

The FastAPI service also publishes a conventional OpenAPI document at https://api.gaussian-beam.com/openapi.json. The public HTTP surface includes /api/health, /api/catalog/fibers, /api/catalog/fiber-collimators, /api/catalog/lenses, /api/simulate, and immutable design-link endpoints. The capability-bound Direct Agent Bridge lives under /api/agent/workspaces/{public_workspace_id}. Workspace owner HTTP routes live under /api/workspaces and require browser-held owner capabilities for administrative actions such as issuing, rotating, or revoking AI connection credentials.

Public clients should prefer MCP for assistant-driven optics workflows because tool annotations and resources describe the intended use directly. Raw HTTP remains available for conventional application integrations and documentation generated from OpenAPI.

Workspace scopes

Generated AI credentials default to read, preview, and revision-read scopes. The workspace:apply scope is granted only when the user explicitly enables auto-apply. The administrative capabilities:manage scope remains a browser-owner capability and is required to issue, rotate, or revoke connection credentials. AI credentials do not receive revisions:restore by default.

Clients must treat a failed scope check as a user-control boundary, not a retry hint. If a write is rejected, ask the user to confirm the intended workspace action inside DiffBeam rather than trying alternate credentials. Human confirmation is the normal path.

Ethical discovery monitoring

Discovery is monitored by static gates and, when separately enabled, redacted, aggregate operational metrics. The site does not generate thin search pages, copied vendor pages, hidden prompt pages, or AI-client-specific keyword variants. Public pages must stay canonical, indexable, and specific to real optics intents: validating optical systems, simulating Gaussian beam propagation, searching components, sharing immutable designs, and previewing workspace updates.