Skip to main content
Fini can connect to your Model Context Protocol (MCP) server so your agent can read customer context and perform approved actions through the tools you already expose. MCP-backed context and work need no manual setup: read tools feed Attributes automatically, and write tools appear as Actions in Rulebook automatically.
Your tool schemas are the contract. Fini syncs them continuously, derives attributes and Actions from them, and stays current when your tools change. There is no field mapping to build and no manual refresh. The configuration that remains is policy: which tools Fini may call, which ones require workflow gating, and which response fields the AI may see.

​
Before you start

You need:
  • A reachable MCP server endpoint, available over HTTPS.
  • Authentication details for the MCP server.
  • A list of tools Fini is allowed to call.
  • Accurate input and output schemas for each tool.
  • At least one Fini bot that should use the tools.
For production use, read tools should usually return in under 2 seconds and write tools in under 5 seconds.
MCP connections are currently set up by the Fini team. It is not yet possible to add an MCP connection yourself from the Fini UI, so have these details ready to share with your Fini contact.

​
Design tools for automatic binding

Fini derives its configuration from your schemas, so schema quality directly determines agent quality. Good MCP tools:
  • Have a single responsibility.
  • Use explicit, well-named input fields. Fini binds inputs by name and format: a field named email binds to the verified session email, and customer_id binds to a customer ID returned by an earlier tool call.
  • Write descriptions for a reader who has never seen your system. The agent uses the description to decide when to call the tool.
  • Declare an outputSchema. Fini derives attributes and Action outputs from it. Tools without one still work: Fini infers the shape from the first successful responses and treats that as the schema until your server declares one.
  • Declare tool annotations. Fini reads readOnlyHint, destructiveHint, and idempotentHint to classify tools and set safe defaults.
  • Return only the fields the agent needs, in structured JSON, instead of full internal records.
  • Return predictable error fields when a request cannot be completed.
Example read tool:
Example write tool:
If a write tool declares an idempotency_key input, Fini generates and injects the key automatically, one per conversation and intent, so retries never apply the same change twice.

​
Connect your MCP server

Share the following with your Fini contact:
  • A connection name.
  • The MCP server URL.
  • The authentication method and the required credentials. Share credentials through a secure channel, not in plain email or chat.
  • The list of tools Fini is allowed to call.
The Fini team creates the connection and runs the initial sync. Every tool your server exposes appears in the connection’s tool catalog. The tools you listed are enabled. Everything else stays Discovered: visible in the catalog, never callable.

​
How Fini uses your tools

​
Read tools become context automatically

When a read tool is enabled, its output schema is registered immediately. Every response field becomes an attribute named connection.tool.field, for example billing.get_customer_context.plan. There is no Attribute to create and no response mapping to maintain. At runtime, the agent decides which enabled read tools to call based on their descriptions and the conversation. Inputs resolve automatically from verified session data (a signed widget token, integration metadata) and from fields already collected in the conversation. If a required input is unavailable, the tool is skipped and the agent works without it, or asks the customer when the field is something a customer can reasonably provide. Skipped tools and their missing inputs appear in the AI Steps trace in Inbox.

​
Write tools become Actions automatically

Every enabled write tool appears as an Action in Rulebook, grouped under its connection. The tool’s input schema defines the Action inputs and its output schema defines the Action outputs. There is nothing to author. Write tools never run on their own. By default a write tool executes only inside a Rulebook Tool node, after any Check nodes you place before it:
1

Create or edit the rule

Open Rulebook and open the rule that should trigger the workflow.
2

Add the guards

Add any Check or Read nodes that must pass before the work happens.
3

Add a Tool node

Select the write tool. Inputs resolve at runtime the same way read tool inputs do: schema-guided, from attributes and the conversation. When you need determinism for a specific input, pin it. A pinned binding ties the input to a specific attribute or a fixed value and overrides automatic resolution.
4

Add a Reply node

Reference the tool’s output fields by name, exactly as they appear in the schema.
5

Test and publish

Run the flow with test records, then publish the rule.

​
Field visibility

Rulebook can use every returned field. What the AI sees follows policy defaults: Fields hidden from the AI are also redacted in AI Steps traces. Override the default per field only when it is wrong for your data, for example to hide is_vip from generated replies while keeping it available to Rulebook checks.

​
Automatic schema sync

Fini keeps every connection’s tool catalog current. When your server supports it and a session is live, Fini subscribes to tools/list_changed notifications and re-syncs immediately. Otherwise Fini polls tools/list on a short interval and diffs the result against the stored snapshot. Every detected change is classified and handled automatically:
  • Additive changes, such as a new optional input, a new output field, or an updated description, apply silently. New output fields become attributes as soon as the sync lands.
  • New tools appear in the catalog as Discovered and stay disabled until enabled. Nothing your server adds becomes callable on its own.
  • Breaking changes, such as a renamed or removed required input, a removed output field that a rule references, or a deleted tool, mark the tool Degraded. Fini lists every rule and bot that references it, notifies workspace admins, and routes affected Tool nodes to their Fallback path until the change is resolved. A Degraded tool returns to Enabled once a sync validates cleanly against every rule that uses it.
Because sync is continuous, additive changes need no versioning on your side. For hard breaks, such as renaming a required input or restructuring a response, a versioned tool remains the clean path:
1

Add the versioned tool

Add cancel_subscription_v2 to your server. It appears as Discovered on the next sync.
2

Repoint the rule

Enable the new tool and point the affected Tool node at it.
3

Remove the old tool

Remove it from your server after it goes unused. The removal syncs automatically.

​
Testing

Test each layer before publishing:
1

Connection test

Run by the Fini team during setup. Confirms Fini can reach the MCP server and authenticate.
2

Sync check

The tool catalog shows every tool with its current schema, status, and last-synced time.
3

Tool dry run

Run any enabled tool from the catalog with test inputs. Read tools show the derived attributes and their values. Write tools validate inputs against the schema before sending, so always run them against test records.
4

Rulebook test

Confirms the write tool runs only in the intended workflow.
5

Inbox review

The AI Steps trace shows every tool call, the resolved inputs, the returned outputs, and which fields were redacted.

​
Security recommendations

  • Enable only the tools Fini needs. Everything else stays Discovered and is never callable.
  • Never return secrets or access tokens. Fini’s redaction of secret-patterned fields is a backstop, not a substitute.
  • Use least-privilege credentials for the MCP connection.
  • Declare an idempotency_key input on every write tool so Fini can inject one.
  • Review AI Steps after testing to confirm sensitive values are redacted.
Annotations are trusted as your declaration about your own systems. A write tool mislabeled with readOnlyHint: true bypasses Rulebook gating, so label annotations correctly. Any tool without readOnlyHint is treated as a write tool by default.

​
Example workflow

A cancellation workflow with this model:
  1. A customer asks to cancel their subscription.
  2. The agent calls get_customer_context. The email input resolves from the signed widget token.
  3. customer_id, plan, and subscription_status are available as attributes the moment the response lands.
  4. Rulebook matches the cancellation intent.
  5. A Check confirms billing.get_customer_context.customer_id is present.
  6. A Read node captures the cancellation reason.
  7. The Tool node runs cancel_subscription. customer_id resolves from the attribute, reason from the Read node, and idempotency_key is injected by Fini.
  8. A Reply node confirms the cancellation using confirmation_id, refund_amount, and effective_date.
The only configuration that existed here is that the tool was enabled and the rule was built. Everything else came from the schema, and when the schema changes, Fini follows it.

​
Why your MCP tools aren’t working

Confirm the tool is exposed by the MCP server and returned by tools/list, and that it has a valid input schema. Then check the connection’s last-synced time to confirm a sync has run since the tool was added.
Confirm the tool is Enabled, not Discovered. If it is, the most common cause is a vague description: the agent decides when to call a tool from its description, so it must say when the tool should be used. Also confirm a required input is resolvable from session data or the conversation. Skipped tools and their missing inputs are listed in the AI Steps trace.
Check the AI Steps trace to confirm the read tool actually ran. If it did, confirm the response includes the field. Fini derives attributes from the declared schema, so responses that omit declared fields produce empty attributes.
Confirm the tool is wired into a published Rulebook rule assigned to the responding bot, that upstream Check nodes pass, and that required inputs resolve. Pinned bindings must point at attributes that exist in the conversation. Also confirm the tool is not marked Degraded.
Confirm the tool response matches its declared output schema, and that the Reply node references output field names exactly as they appear in the schema.
Your server changed the tool’s schema in a way that breaks a rule that uses it. Review the flagged diff in the catalog, then either restore the previous schema on your server or update the affected rules to match the new one. The tool returns to Enabled on the next clean sync.
The Fini team runs this test while setting up or updating the connection. If it fails, confirm the server URL is reachable from Fini, the server supports the configured transport, the credentials you shared are valid and current, any firewall allowlist includes Fini outbound traffic, and the MCP server returns a valid tool list. After fixing the issue, ask the Fini team to retest the connection.