Custom Tools (API & MCP)

Overview

Agentic Fabriq supports two types of custom tool integrations beyond the built-in connectors (Gmail, Slack, etc.):

• OpenAPI Tools: Import an OpenAPI/Swagger specification to create tools from REST API endpoints
• MCP Server Tools: Connect to an external MCP server and discover its tools automatically

Both types follow the same zero-trust permission model: actions are denied by default until an admin explicitly grants them.

Tool Types

Admin Setup — OpenAPI Tools

1. Create the Tool

1. Navigate to Admin Console > Custom Tools > "Add Integration"
2. Select type: OpenAPI
3. Enter a name and slug (auto-generated from name)
4. Optionally select a Network Connector if the API is on a private network

2. Import the Specification

1. Upload a JSON/YAML file or enter the spec URL
2. Preview parsed actions and scopes before importing
3. Click "Import" to create actions and scopes from the spec

3. Review Actions and Scopes

• Each API endpoint becomes an action with a detected risk level (read, write, delete, external)
• Risk levels can be overridden by the admin
• Mapping status: mapped (admin verified), inferred (auto-detected), unverified (needs review)

4. Configure OAuth Credentials

1. Set auth type (OAuth 2.0, API Key, Bearer Token)
2. Enter authorize URL, token URL, client ID, client secret
3. Configure scope separator and token placement

5. Assign Permissions

• Default: all actions are denied for all users
• Grant per-user permissions: Custom Tools > tool detail > Members tab
• Or create scope groups and assign users to groups
• The scope pool defines which OAuth scopes are requested during user connection

6. Mark Setup Complete

Once configured, the tool becomes visible to users.

Admin Setup — MCP Server Tools

1. Create the Tool

1. Navigate to Admin Console > Custom Tools > "Add Integration"
2. Select type: MCP Server
3. Enter a name, slug, and the MCP server URL

2. Discover Authentication Requirements

Click "Discover Auth" to probe the server for RFC 9728/8414 OAuth metadata. If the server requires OAuth, enter client credentials.

3. Admin Connection

Complete the "Admin Connect" step to establish your own connection to the MCP server. This allows Agentic Fabriq to discover tools from the server.

4. Discover Tools

1. Click "Discover Tools" to fetch the list of available tools from the MCP server
2. Each discovered tool becomes an action
3. Bulk enable/disable which tools are available to users

5. Assign Permissions

Same as OpenAPI: all actions are denied by default. Grant per-user permissions or use scope groups.

6. Mark Setup Complete

Once configured, the tool becomes visible to users.

User Workflow

1. Browse available custom tools in the dashboard (My Tools section)
2. Click "Connect" to initiate OAuth with the external service
3. Grant the requested scopes
4. Once connected, agents can invoke the custom tool's actions via MCP
5. View connections and manage scopes in My Tools > Custom Tool Connections

Zero-Trust Permission Model

Permission layers:

1. Admin action limits: Which actions a user is allowed to execute (toggle per action per user)
2. Scope groups: Group actions and scopes together, then assign users to groups
3. User OAuth scopes: What the user actually granted during OAuth
4. Effective permission: Intersection of all three layers

The scope pool defines the default set of scopes requested if an action doesn't specify explicit scopes.

Execution Failure Diagnostics

• When a user's tool call fails with 403 (insufficient scope), it is recorded as an execution failure
• Admins can view failures: Custom Tools > tool detail > Diagnostics tab
• Review the failure (which action, which user, what scope was missing)
• Resolve by granting the missing scope or updating the action's scope mapping
• Mark failures as resolved once addressed

Network Connectors

For APIs on private networks (not publicly accessible), use a Network Connector.

• Network connectors create a secure tunnel between Agentic Fabriq and your private infrastructure
• Select the network connector when creating the custom tool
• All API requests will be routed through the tunnel