Integration Patterns

FCC supports four primary integration shapes. Which one you pick depends on where the boundary between your application and FCC sits and on how tightly the two are allowed to couple. This page walks through all four with example code, so you can match the shape to your constraints.

Pattern 1 — Python library

When it fits. Your application is already Python, runs in the same process as the FCC calls, and you control both deployments. This is the simplest pattern and the one the notebooks and most of the internal code take.

from fcc.personas.registry import PersonaRegistry
from fcc.simulation.engine import SimulationEngine
from fcc.scenarios.loader import ScenarioLoader

registry = PersonaRegistry.from_package_data()
scenarios = ScenarioLoader.from_package_data()
engine = SimulationEngine(registry=registry, mode="mock")

trace = engine.run(scenarios.get("basic_fcc_cycle"))

Coupling is strong: you import FCC, link to its version, and are exposed to any schema changes. Use this inside Python-first projects where the FCC version can be pinned in your own pyproject.toml.

Pattern 2 — MCP tool server

When it fits. You want to expose FCC capabilities to an LLM client or another agent runtime that speaks the Model Context Protocol. The MCP server in src/fcc/protocols/mcp/server.py wraps the persona registry, the simulation engine, and the compliance auditor as MCP tools.

fcc protocol mcp-serve --port 9001

Your client (Claude Desktop, an in-house runtime, or a custom agent) declares FCC as an MCP server and calls tools such as fcc.persona.lookup, fcc.simulation.run, or fcc.compliance.audit. The LLM never needs to know FCC's internal types; it sees structured JSON-RPC tool calls.

Coupling is loose: you are tied to the MCP contract, not to FCC's Python API. Use this when your runtime is polyglot or LLM-native.

Pattern 3 — A2A agent

When it fits. You are building a multi-agent system where each agent publishes an Agent Card and responds to JSON messages over the A2A protocol. FCC's A2A server (src/fcc/protocols/a2a/server.py) turns each persona in the registry into an addressable agent with its R.I.S.C.E.A.R. contract as the public interface.

fcc protocol a2a-serve --port 9002

Other A2A-speaking agents (AOME's auditor, CONSTEL's federation node, PHOENIX's gate evaluator) send messages addressed to a specific persona and get structured responses back. The WebSocket bridge on port 8765 streams the same interactions to the AURORA visualizer.

Coupling is loose and bidirectional. Use this when you need persona interactions that look and feel like message passing between autonomous agents rather than function calls.

Pattern 4 — CLI consumer

When it fits. Your application is driven by a build system, a CI/CD pipeline, a shell script, or a Makefile. The FCC CLI (fcc entry point, defined in src/fcc/scaffold/cli.py) exposes validation, doc generation, compliance audits, model-card generation, and scaffold operations as composable subcommands.

fcc validate
fcc generate-docs --output-dir ./generated-docs
fcc compliance-audit --output ./audit.json
fcc benchmark --suite baseline

Your CI job invokes these commands and treats their exit codes and output artifacts as the contract. There is no Python coupling at all — FCC behaves like any other tool in your toolchain.

How to choose

Pattern	Coupling	Latency	Best when
Python library	Tight	In-process	Same-language, same-version, same-deploy.
MCP tool server	Loose	RPC	LLM-native runtimes; polyglot consumers.
A2A agent	Loose, symmetric	RPC	Multi-agent systems with persona semantics.
CLI consumer	None	Process start	Build pipelines, CI, artifact producers.

A single deployment often combines several patterns. Athenium, for example, declares a VocabularyProviderPlugin (library-ish coupling for cross-vocab resolution) and consumes FCC's A2A server for runtime persona messaging.

Choosing between VocabularyProviderPlugin and the others

If your goal is to let FCC validate that your application's concepts map cleanly to FCC concepts, VocabularyProviderPlugin is the right seam. See Plugin Development for the walk through. It layers cleanly on top of any of the four patterns above — a VocabularyProviderPlugin is not a runtime protocol; it is a metadata contract discovered at import time.

Related FCC documentation

• Plugin Development — authoring your first VocabularyProviderPlugin.
• Quick Start — the Python-library pattern in detail.
• Testing Guide — patterns for testing each of the four integration shapes.
• API Boundaries — which boundary each pattern crosses.
• Context Diagram — where MCP, A2A, and the WebSocket bridge sit in the ecosystem.
• For Professionals — Integration Guide — CI/CD, observability, and toolchain integration when the CLI pattern is your primary seam.
• Notebook 13_protocol_integration.ipynb — protocol deep-dive.
• Notebook 28_web_frontend_walkthrough.ipynb — the WebSocket bridge end-to-end.