FDE 3: Skills, tools and MCP

Capabilities turn a scoped but empty environment into one that does the workload. Add them piece by piece, verifying each. MCP wiring follows a hard model (catalog vs. install), described below from the MCP admin sources. The registry reference lives under MCP registry; this page is the field verification flow.

Grounding, practice vs product: product behavior below (catalog tables, install rows, surfaces, endpoints, OAuth profiles, verify-before-use rules) is from the pasted MCP admin (MCP_SERVERS_ADMIN) and connector-contract sources. Practice (sequencing rules, probe checklists, the capabilities register, training flows) is field practice recommended by this guide. It describes how to rehearse and verify, not what the product enforces.

What each layer contributes

Layer	Contributes
Skills	Repeatable procedures, how the workload is done, step by step
Tools	Atomic capabilities the agent invokes (often connector-backed via bindings)
MCP wiring	The channel exposing external capabilities into the session

Skills and tools shape agent behavior; MCP wiring feeds tools. The session does the workload behind approval gates.

MCP: catalog vs. tenant install (product behavior, from source)

The model has two sides. Do not confuse them:

Side	Tables	Scope / guard
Platform catalog	ai.mcp_catalog_source, ai.mcp_catalog_server, ai.mcp_catalog_server_version. Preshos-managed catalog entries.	Managed by the platform; requirePlatformOps
Tenant install	ai.mcp_servers rows	Per org_id. One tenant’s installs never leak into another’s.

Two ways a tenant gets an MCP server (both product behavior, pick the right one):

Path	When	Surface
Catalog install	The server exists in the platform catalog	POST /api/v1/mcp-servers/install-from-catalog. Installs a catalog version into the tenant’s ai.mcp_servers.
Custom tenant MCP	No catalog entry fits, so the tenant defines its own server	/ai/mcp-servers/new. Creates a tenant-owned ai.mcp_servers row with catalog_server_id null.

Custom MCP is allowed, not a workaround, with guards: operational rechecks plus fingerprint recheck and DNS-pinned guarded fetch as applicable before use. Catalog installs get the same verify-before-use treatment.

Browse and install at /ai/mcp-servers, discover at /ai/mcp-servers/discover, create custom at /ai/mcp-servers/new, install from catalog via POST /api/v1/mcp-servers/install-from-catalog.

• Platform OAuth profiles (from source): Google Drive com.google.drive/mcp, HubSpot com.hubspot/mcp. Anything else claiming profile status needs source confirmation.
• Verify before use: fingerprint recheck and DNS-pinned guarded fetch before use. An MCP capability is not trusted because it is installed. It is rechecked (fingerprint) and fetched through the guarded path (DNS-pinned) each time it matters.

MCP install checklist (per tenant, practice)

• Path chosen deliberately: catalog install (ai.mcp_catalog_server_version to ai.mcp_servers) or custom tenant MCP (catalog_server_id null via /ai/mcp-servers/new). Recorded which one and why.
• Installed to the tenant’s ai.mcp_servers under the correct org_id
• OAuth profile confirmed if applicable (com.google.drive/mcp, com.hubspot/mcp)
• Fingerprint recheck and DNS-pinned guarded fetch observed working before pilot users arrive (custom MCP: operational rechecks also confirmed)
• Install recorded in the capabilities register (below) with scope and date

Connector-backed tools: bindings required

A connector tool is only real for the tenant when its binding exists: install settings.object_mappings scoped to org, package, and connection, identity binding:<uuid> in ai.connector_object_map, destination from target-catalog.ts (for example targetObject: 'work-items' with workItemTypeId; never retired tasks/deliverables). Full rules: SDK concepts, Extend.

• Binding coordinates confirmed for this tenant (org, package, connection), not “the connector exists”
• Registered-adapter reality check: HubSpot and ConnectWise PSA are registered; Salesforce scaffolds are not implementations; outbound HubSpot writes disabled

Sequencing rule: tools, then skills, then wiring (practice)

1. Tools first. Confirm each tool standalone in a test session. A skill built on broken tools teaches the agent to fail confidently.
2. Skills second. Encode the procedure once tools are solid: order of operations, what to gather before acting, when to stop and ask.
3. Wiring throughout, verified last. Confirm the full chain end to end: skill to tools (via MCP install where applicable), under environment policy, gates firing.

Per-piece verification checklist (practice)

For each skill, tool, or wired capability:

• Works standalone in a test session
• Failure modes observed once on purpose (external slow, down, or empty, with output staying sane)
• Scope respected: reaches only its intended systems and data
• Approval behavior as designed (flows where smooth, gates where risky)
• MCP-backed: fingerprint recheck and guarded fetch verified, not assumed
• Added to the capabilities register with kind, rationale, and verification date

Composition pitfalls (practice, symptoms seen in pilot)

Pitfall	Symptom in pilot	Prevention
Skill assumes tools not in the environment	Agent improvises or stalls	Skill to tool-table cross-check before pilot
Overlapping tools	Inconsistent sessions, confused approvals	One canonical tool per action
Wired capability bypasses policy	Risky work flows ungated	Verify gates on the wired path, not just native
Install in wrong org scope	Another tenant’s data reachable (or nothing works)	Confirm org_id on the ai.mcp_servers row
Unverified “it worked in dev”	First tenant failure is live	Nothing enters pilot unverified in-environment

The capabilities register (practice)

Extend the environment spec with: capability, layer (skill, tool, MCP install and binding), status (specified or verified), verification date, notes. The pilot reads this register; the handoff hands it over.

Next: Approvals design gates the risky parts.