Connector Architecture

Copilot vs Hub

The architecture supports two integration scales: Copilot embeds into a host system’s UI. Users interact with AI without leaving their familiar interface. It can use multiple connectors (host DB + notification service, etc.). Hub is a standalone portal that connects all systems. It’s not embedded in any single system — it’s the central intelligence layer where systems meet AI. Same connector architecture, different delivery. A Copilot uses the same ConnectorToolAdapter as a Hub.

Core Principle

The client changes zero code. FIM One bridges into their systems proactively — reading their databases, calling their APIs, pushing to their message bus. The client provides only credentials and network access.

Three-Layer Architecture

Each layer has a distinct responsibility:

Layer	Owns	Changes when…
Platform	Orchestration, multi-tenant, UI	New platform features ship
Connector Governance Layer	Enterprise governance policies	Security/compliance requirements change
MCP Protocol	Transport, tool interface standard	Never (open standard)
Legacy System	Business data and logic	Never (that’s the whole point)

Why MCP as the Transport Layer

Adapters are implemented as MCP Servers. This is a deliberate architectural choice:

Reuse: FIM One already ships an MCP Client (v0.3). Adding a legacy system adapter reuses the same infrastructure as adding any MCP tool.
Standard protocol: MCP is an open standard. No proprietary protocol to invent or maintain.
Ecosystem: Third-party MCP Servers (databases, APIs, SaaS tools) work out of the box.
Process isolation: Each MCP Server runs as a separate process. A misbehaving adapter cannot crash the platform.

What MCP alone does not provide

The Connector Governance Layer adds enterprise governance that raw MCP lacks:

Concern	MCP	Connector Governance Layer
Read-only enforcement	No	`read_only` flag on operations; write blocked by default
Audit logging	No	Every tool call recorded (timestamp, user, tool, params, result)
Auth passthrough	No	Proxy host-system auth; agent acts on behalf of logged-in user
Confirmation gate	No	Write operations require human approval (SSE `confirmation_required`)
Circuit breaker	No	Connection failure triggers graceful degradation
Operation classification	No	Operations tagged as read/write/admin with per-level policies
Column-level masking	No	Database columns marked as personal data return a mask instead of their values

Database column masking

A database connector is often configured with one privileged account, so every caller reaches the same tables. Marking a column as PII in the connector’s schema manager narrows what the agent can see from it:

the column stays listed in the schema, tagged, so the model knows it exists and does not invent a substitute for it;
any value returned under that column name is replaced with *** before the result reaches the model, including through SELECT *;
the call log records which columns were masked, alongside whether the connector was in read-only mode.

Matching is by column name, which is the only identifier a result set carries. Two limits follow, and both are deliberate: the database still uses the column, so WHERE salary > 5000 filters normally, and a query that renames the column (SELECT salary AS s) returns unmasked values. When the requirement is that the query account cannot read a column at all, grant that in the database and point the connector at the restricted account. The owner’s own query playground is not masked. Masking governs what reaches an agent and the conversation transcript, not what the person who configured the connection can inspect.

Why not invent a custom protocol

Protocol is commodity. The technical value is in the adapters themselves (domain knowledge, schema mapping, edge-case handling) and the governance layer (audit, auth, safety). Inventing a transport protocol would add maintenance cost without adding capability. Stripe uses HTTPS; Docker uses cgroups; FIM One uses MCP.

Deployment Model

Everything runs in a single Docker Compose deployment. The client installs nothing.

All provided by FIM One. Client provides only:

Database credentials (read-only account recommended)
API endpoints and keys (if available)
Network whitelist access

Access hierarchy: FIM One adapts to whatever access the client can provide:

What client has	How FIM One connects
API with documentation	HTTP API adapter (best case)
API without documentation	HTTP API adapter + manual schema mapping
Database access only	Database adapter (direct SQL, read-only by default)
Database + message bus	Database adapter + message push adapter

Agent-Connector Decoupling

The agent sees connectors as ordinary tools. It does not know or care whether a tool is built-in, a third-party MCP Server, or a legacy system connector. This means:

Adding a new system = adding a connector config. Agent code does not change.
Removing a connector = removing the config. No code changes.
The same agent can use built-in tools and connectors in a single task.

Hot-Plug Evolution

Version	How to add a new connector	Restart required?
v0.6	Write a Python MCP Server with Connector Governance Layer, add to docker-compose	Redeploy
v0.8	Write a YAML/JSON config, platform generates MCP Server	Restart
v1.0	Upload OpenAPI spec, AI generates config automatically	No restart (hot-plug)

Enterprise deployments are “implement once, run for months” — hot-plug is a v1.0 convenience, not a v0.6 requirement.

Data Flow Example

User: “Check all overdue contracts from the finance system and push a summary to Lark.”

1. User sends message via Portal / API

2. FIM One (ReAct mode):
   Think: I need to query the finance DB for overdue contracts, then push to Lark.

3. Act: contract_query(status="overdue", days_past_due=">30")
   → Connector Governance: audit log, read_only check (pass)
   → MCP Server: translates to SQL
   → Client DB: SELECT * FROM contracts WHERE status='overdue' AND ...
   ← Returns 7 overdue contracts

4. Think: Found 7 overdue contracts. I'll summarize and push.

5. Act: lark_push(message="7 overdue contracts found: ...")
   → Connector Governance: audit log, write operation → confirmation gate
   → User approves via Portal
   → MCP Server: POST to Lark webhook
   ← Push successful

6. Answer: "Found 7 overdue contracts. Summary pushed to Lark group."

Connector Standardization Levels

Level	Version	Approach	Who builds it
Level 1	v0.6	Python MCP Server with Connector Governance	FIM One developer
Level 2	v0.8	YAML/JSON config, platform auto-generates MCP Server	Implementation engineer (no Python needed)
Level 3	v1.0	Upload OpenAPI/Swagger spec, AI generates config	AI (with human review)

Relationship to Existing MCP Ecosystem

FIM One’s MCP Client (shipped in v0.3) already supports third-party MCP Servers. Legacy system adapters are simply domain-specific MCP Servers built with the Connector Governance Layer for enterprise governance. The Connector Governance Layer does not replace MCP — it extends MCP with the governance layer that enterprise legacy system integration requires.

Architecture

Execution Engines

Strategy

Connector Architecture

Copilot vs Hub

Core Principle

Three-Layer Architecture

Why MCP as the Transport Layer

What MCP alone does not provide

Database column masking

Why not invent a custom protocol

Deployment Model

Agent-Connector Decoupling

Hot-Plug Evolution

Data Flow Example

Connector Standardization Levels

Relationship to Existing MCP Ecosystem

​Copilot vs Hub

​Core Principle

​Three-Layer Architecture

​Why MCP as the Transport Layer

​What MCP alone does not provide

​Database column masking

​Why not invent a custom protocol

​Deployment Model

​Agent-Connector Decoupling

​Hot-Plug Evolution

​Data Flow Example

​Connector Standardization Levels

​Relationship to Existing MCP Ecosystem

Copilot vs Hub

Core Principle

Three-Layer Architecture

Why MCP as the Transport Layer

What MCP alone does not provide

Database column masking

Why not invent a custom protocol

Deployment Model

Agent-Connector Decoupling

Hot-Plug Evolution

Data Flow Example

Connector Standardization Levels

Relationship to Existing MCP Ecosystem