Tool Integration

Register MCP tools, configure tool sets, and grant tool access

Builder/Admin Guide: Tool Integration

This guide covers how to register MCP (Model Context Protocol) tools, grant them to agents, and monitor their usage. It is intended for builders who create tools and grant them to agents, and admins who manage tool security and access policies.

Where to manage tools: Agent Studio > Tools (http://localhost:3001/studio/tools).

Table of Contents

• What Are MCP Tools?
• The MCP Gateway (L5)
• The MCP Tool Registry
• Tool Structure
• Registering a New MCP Tool
• Granting Tools to Agents
• Tool Signing with Sigstore
• Tool Grant Enforcement at Runtime
• Monitoring Tool Usage
• Built-in Mock Tools
• Building Custom MCP Tools
• Common Tool Integration Patterns
• Troubleshooting Tool Issues

What Are MCP Tools?

MCP (Model Context Protocol) tools are external capabilities that agents can invoke to interact with systems, services, and data sources. Tools are the bridge between an agent's reasoning (LLM-powered) and the real world (APIs, databases, services).

Examples of what tools do:

• Search a knowledge base for relevant documents.
• Create a support ticket in Jira.
• Send an email or Slack message.
• Query a database.
• Scrape a web page for structured data.
• Book a calendar event.
• Execute code in a sandbox.

MCP is the universal interoperability protocol that standardizes how agents discover, authenticate with, and invoke tools regardless of whether the agent runs on the Pro-Code or n8n runtime.

The MCP Gateway (L5)

The MCP Gateway sits at Layer 5 of the platform architecture. It is the central enforcement point for all tool interactions:

Agent --> MCP Gateway --> Tool Server
                |
                +-- Grant Check (is this tool granted to this agent?)
                +-- Rate Limit Check (has the agent exceeded its rate limit?)
                +-- Time Window Check (is the tool available at this time?)
                +-- HITL Check (does this invocation require human approval?)
                +-- Audit Log (record the decision and invocation)

Gateway Responsibilities

The MCP Tool Registry

The Tool Registry is the catalog of all available tools on the platform. It is accessible in Agent Studio at /studio/tools.

Browsing the Registry

The Tools page displays all registered tools with:

• Tool name and description -- What the tool does.
• MCP Endpoint -- The tool's server address (e.g., mcp://tools.internal/kb-search).
• Runtime compatibility -- Which runtimes can use this tool (procode, n8n, or both).
• Risk level -- low, medium, high, or critical (color-coded badge).
• Category -- read-only, write, external-comms, financial, or destructive.
• Usage count -- How many times the tool has been invoked.
• Granted agents -- Which agents currently have access to this tool.

Filtering Tools

You can filter the tool registry by:

• Risk level -- Show only tools of a specific risk level.
• Category -- Filter by tool category.
• Runtime -- Show tools compatible with a specific runtime.
• Search -- Search by tool name or description.

Tool Structure

Every MCP tool has the following attributes:

interface Tool {
  id: string;                    // Unique tool identifier (e.g., 'tool-1')
  name: string;                  // Display name (e.g., 'Knowledge Base Search')
  description: string;           // What the tool does
  mcpEndpoint: string;           // MCP server endpoint (e.g., 'mcp://tools.internal/kb-search')
  runtime: 'procode' | 'n8n' | 'both';  // Compatible runtimes
  riskLevel: 'low' | 'medium' | 'high' | 'critical';
  category: 'read-only' | 'write' | 'external-comms' | 'financial' | 'destructive';
  inputSchema: object;           // JSON Schema defining expected input
  outputSchema: object;          // JSON Schema defining expected output
  usageCount: number;            // Total invocation count
  grantedAgentIds: string[];     // Agents that currently have access
}

Input and Output Schemas

Tools define their interface using JSON Schema. The input schema specifies what parameters the agent must provide when invoking the tool, and the output schema describes the structure of the tool's response.

Example Input Schema (Knowledge Base Search):

{
  "type": "object",
  "properties": {
    "query": { "type": "string" },
    "maxResults": { "type": "number", "default": 10 },
    "filters": {
      "type": "object",
      "properties": {
        "category": { "type": "string" },
        "dateRange": { "type": "string" }
      }
    }
  },
  "required": ["query"]
}

Example Output Schema (Knowledge Base Search):

{
  "type": "object",
  "properties": {
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "title": { "type": "string" },
          "content": { "type": "string" },
          "score": { "type": "number" }
        }
      }
    },
    "totalCount": { "type": "number" }
  }
}

Registering a New MCP Tool

Step-by-Step Registration

1. Navigate to Studio > Tools (/studio/tools).
2. Click Register Tool (or equivalent create button).
3. Fill in the tool details:

1. Click Save to register the tool.

Choosing the Right Risk Level

Choosing the Right Category

Granting Tools to Agents

Tools are not automatically available to agents. Each agent must be explicitly granted access to the tools it needs. This is the Agent -> Tool dimension of access control (Dimension 2).

Granting from the Agent Designer

1. Open the agent in the Agent Designer (/studio/agents/[id]).
2. Navigate to the Tools tab.
3. Browse or search the tool catalog.
4. Check the tools you want to grant to this agent.
5. For each granted tool, configure conditions:

1. Set the Dynamic Discovery toggle:

   • false (default, recommended): The agent can only use tools explicitly listed in its grants.
   • true: The agent can discover and request access to tools not in its grants. Use with caution.

2. Set Max Tool Calls Per Execution (circuit breaker): Limits the total number of tool calls an agent can make in a single execution. Default: 20.

Granting from the Tool Page

You can also grant tools from the tool's detail page:

1. Navigate to Studio > Tools (/studio/tools).
2. Click on a tool.
3. View the Granted Agents section.
4. Click Grant to Agent and select the target agent.
5. Configure permissions and conditions.

Bulk Granting

For tools that should be available to many agents, use the bulk grant feature:

1. Navigate to the tool's detail page.
2. Click Bulk Grant.
3. Select agents by tag or capability match.
4. The tool is granted to all matching agents with default permissions.

Tool Grant Configuration Example

{
  "toolGrants": {
    "tools": [
      {
        "toolId": "tool-1",
        "permissions": ["read", "execute"],
        "conditions": {
          "maxCallsPerHour": 100
        }
      },
      {
        "toolId": "tool-3",
        "permissions": ["execute"],
        "conditions": {
          "requireApproval": true,
          "timeWindow": { "start": "09:00", "end": "17:00" }
        }
      },
      {
        "toolId": "tool-4",
        "permissions": ["read", "write", "execute"],
        "conditions": {
          "maxCallsPerHour": 500
        }
      }
    ],
    "dynamicDiscovery": false,
    "maxToolCallsPerExecution": 20
  }
}

This configuration means:

• Tool 1 (Knowledge Base Search): Read and execute. Up to 100 calls per hour. No approval needed.
• Tool 3 (Send Email): Execute only. Each invocation requires human approval. Only available during business hours (09:00--17:00).
• Tool 4 (SQL Query): Full access (read, write, execute). Up to 500 calls per hour. No approval needed.
• The agent cannot discover tools outside this list.
• The agent is limited to 20 total tool calls per execution.

Tool Signing with Sigstore

All tools deployed in production are signed using Sigstore to ensure integrity and provenance.

What Sigstore Provides

• Integrity verification -- Ensures the tool has not been tampered with since it was signed.
• Provenance tracking -- Records who built and deployed the tool, and when.
• Transparency log -- All signatures are recorded in a public transparency log for auditability.

How It Works

1. When a tool is deployed, its artifact (code, configuration, container image) is signed using Sigstore's keyless signing.
2. The signature is stored alongside the tool in the registry.
3. At runtime, the MCP Gateway verifies the tool's signature before routing requests to it.
4. If verification fails, the tool invocation is blocked and an alert is raised.

For Tool Developers

You do not need to manually sign tools. The deployment pipeline handles signing automatically. You can verify a tool's signature status in the tool's detail page in the registry.

Tool Grant Enforcement at Runtime

How Tool Calls Are Checked

When an agent invokes a tool, the following checks occur at the MCP Gateway:

1. Agent calls mcp.tool.invoke(toolId, input)
2. MCP Gateway receives the request
3. Grant Check:
   - Is this toolId in the agent's tool grants? If NO --> 403 Forbidden
   - Does the agent have the required permission (read/write/execute)? If NO --> 403 Forbidden
4. Condition Checks (if conditions are configured):
   - Rate Limit: Has the agent exceeded maxCallsPerHour? Check Redis counter.
     If YES --> 429 Too Many Requests
   - Time Window: Is the current time within the allowed window?
     If NO --> 403 Forbidden (outside allowed hours)
   - HITL Approval: Is requireApproval set to true?
     If YES --> Pause execution, create approval request, wait for decision
5. If all checks pass --> Forward request to tool MCP server
6. Audit log entry created (whether allowed or denied)

What Happens When a Grant Check Fails

When a tool call is denied, the MCP Gateway returns an error to the agent:

• 403 Forbidden -- The tool is not granted to this agent, the agent lacks the required permission, or the time window restriction is violated. The tool is effectively invisible to the agent.
• 429 Too Many Requests -- The agent has exceeded the configured rate limit for this tool. The agent should wait before trying again.

The denial is recorded in the audit log and appears as a yellow span in the Trace Explorer.

Rate Limit Enforcement

Rate limits are tracked in Redis using sliding window counters. Each unique (agentId, toolId) pair has its own counter that resets hourly.

When an agent approaches its rate limit:

1. The first 80% of calls proceed normally.
2. At 80--100% of the limit, warning spans appear in the trace.
3. At 100%, subsequent calls are rejected with 429 until the window resets.

Monitoring Tool Usage

Trace Explorer

The Trace Explorer in Studio (/studio/traces) shows tool invocations as spans within execution traces.

For each tool call span, you can see:

• Tool name -- Which tool was invoked.
• Input -- What parameters were sent to the tool.
• Output -- What the tool returned.
• Duration -- How long the tool call took (in milliseconds).
• Status -- success or error.
• Grant check result -- Whether the grant check passed or failed (yellow highlight for denials).

Filtering Traces by Tool Usage

Use the Trace Explorer filters to find traces involving specific tools:

• Filter by agent ID to see all tool usage by a specific agent.
• Filter by status to find failed tool calls.
• Filter by minimum latency to find slow tool calls.
• Filter by minimum cost to find expensive operations.

Admin Security Center

The Admin Console > Security page (/admin/security) includes an Agent -> Tool Grants tab that provides a platform-wide view of:

• All tool grants across all agents.
• Tools with the most grants.
• Agents with the most tool access.
• Recent grant changes (who granted what, when).
• Tools with high-risk grants that lack HITL protection.

Built-in Mock Tools

The platform includes 10 pre-registered mock tools for development and testing. These tools return simulated data and are available in the Tool Registry when running in mock mode.

Tool Inventory

Testing with Mock Tools

In mock mode, tool invocations return simulated success responses. You can use the tool test feature to verify input/output schemas:

1. Navigate to the tool's detail page.
2. Click Test Tool.
3. Provide sample input parameters.
4. View the simulated response (success, result, duration).

Building Custom MCP Tools

MCP Server Specification

A custom MCP tool requires an MCP-compliant server that implements the tool's interface. The server must:

1. Accept invocations via the MCP protocol at the registered endpoint.
2. Validate input against the tool's input schema.
3. Execute the operation (database query, API call, etc.).
4. Return output conforming to the tool's output schema.
5. Handle errors gracefully with structured error responses.

Server Endpoint Format

MCP endpoints follow the format: mcp://<host>/<tool-path>

Examples:

• mcp://tools.internal/kb-search
• mcp://tools.internal/email-sender
• mcp://tools.external/weather-api

Input/Output Schema Design

Design your schemas to be:

• Strict: Use required to mark mandatory parameters.
• Documented: Add description to each property for agent understanding.
• Typed: Use specific types (string, number, boolean, array, object) rather than generic types.
• Bounded: Use enum for constrained values, minimum/maximum for numbers, and maxLength for strings.
• Defaulted: Provide sensible defaults where possible.

Example: Well-Designed Input Schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "The search query to execute against the knowledge base.",
      "minLength": 1,
      "maxLength": 500
    },
    "maxResults": {
      "type": "number",
      "description": "Maximum number of results to return.",
      "default": 10,
      "minimum": 1,
      "maximum": 100
    },
    "filters": {
      "type": "object",
      "description": "Optional filters to narrow search results.",
      "properties": {
        "category": {
          "type": "string",
          "description": "Document category to filter by.",
          "enum": ["faq", "policy", "procedure", "technical"]
        },
        "dateRange": {
          "type": "string",
          "description": "Date range filter.",
          "enum": ["last-week", "last-month", "last-quarter", "all-time"]
        }
      }
    }
  },
  "required": ["query"]
}

Authentication Requirements

Tools that access external services may require authentication. The platform supports:

• API Key -- Stored in Vault and injected by the MCP Gateway at invocation time.
• OAuth 2.0 -- Token exchange handled by the MCP Gateway.
• Mutual TLS -- Using the agent's SPIFFE identity for service-to-service authentication.

Credentials are never exposed to the agent. The MCP Gateway injects authentication headers/tokens when forwarding requests to the tool server.

Testing with the Playground

Before deploying a tool to production:

1. Register the tool in the Tool Registry.
2. Grant it to a test agent.
3. Open the Playground (/studio/playground).
4. Select the test agent.
5. Send messages that should trigger the tool.
6. Review the execution trace to verify:
   • The tool was invoked with correct parameters.
   • The tool returned the expected output.
   • The agent used the tool output appropriately in its response.

Common Tool Integration Patterns

Pattern 1: Read-Only Information Retrieval

Use case: Agent needs to search for and retrieve information.

{
  "toolId": "tool-kb-search",
  "permissions": ["read", "execute"],
  "conditions": {
    "maxCallsPerHour": 200
  }
}

Characteristics:

• Low risk. No side effects.
• High rate limit (frequent searches are expected).
• No HITL required.

Pattern 2: Supervised Write Operations

Use case: Agent creates records in internal systems with human oversight.

{
  "toolId": "tool-create-ticket",
  "permissions": ["read", "write", "execute"],
  "conditions": {
    "requireApproval": true,
    "maxCallsPerHour": 50
  }
}

Characteristics:

• Medium risk. Creates records.
• HITL approval for each write operation.
• Moderate rate limit.

Pattern 3: Time-Restricted External Communications

Use case: Agent sends emails but only during business hours.

{
  "toolId": "tool-send-email",
  "permissions": ["execute"],
  "conditions": {
    "requireApproval": true,
    "timeWindow": { "start": "09:00", "end": "17:00" },
    "maxCallsPerHour": 10
  }
}

Characteristics:

• High risk. External communication.
• HITL approval for every send.
• Business hours only (prevents automated out-of-hours emails).
• Low rate limit (emails should be infrequent).

Pattern 4: High-Throughput Data Processing

Use case: Agent processes data at scale with minimal human intervention.

{
  "toolId": "tool-db-query",
  "permissions": ["read", "write", "execute"],
  "conditions": {
    "maxCallsPerHour": 500
  }
}

Characteristics:

• Medium risk. Database access.
• No HITL (high throughput requires automation).
• High rate limit.
• Rely on guardrails (sql-injection-check, data-leak-prevention) rather than per-call approval.

Pattern 5: Critical Operations with Full Safeguards

Use case: Agent performs destructive operations with maximum oversight.

{
  "toolId": "tool-delete-records",
  "permissions": ["execute"],
  "conditions": {
    "requireApproval": true,
    "maxCallsPerHour": 5,
    "timeWindow": { "start": "10:00", "end": "16:00" }
  }
}

Characteristics:

• Critical risk. Irreversible deletion.
• HITL approval required for every invocation.
• Very low rate limit (5 per hour).
• Restricted to business hours (with buffer on both ends).
• The tool itself requires a confirmation token (defense in depth).

Troubleshooting Tool Issues

Tool Call Returns 403 Forbidden

Cause: The agent does not have a grant for this tool, or it lacks the required permission level.

Resolution:

1. Check the agent's tool grants in the Agent Designer > Tools tab.
2. Verify the tool ID matches what the agent is trying to invoke.
3. Ensure the required permissions (read, write, execute) are granted.
4. Check the Trace Explorer for the specific denial reason.

Tool Call Returns 429 Too Many Requests

Cause: The agent has exceeded the maxCallsPerHour rate limit for this tool.

Resolution:

1. Check the current rate limit in the tool grant conditions.
2. If the limit is too low, increase maxCallsPerHour in the Tools tab.
3. If the agent is legitimately making too many calls, consider optimizing the agent's prompt to reduce unnecessary tool invocations.

Tool Call Blocked by Time Window

Cause: The tool has a timeWindow condition and the current time is outside the allowed window.

Resolution:

1. Check the time window configuration in the tool grant.
2. Verify the time zone being used (platform default or agent-specific).
3. Adjust the time window if business hours need to be extended.

Tool Call Pending HITL Approval

Cause: The tool has requireApproval: true and the invocation is waiting for human approval.

Resolution:

1. Check the Approvals page (/portal/approvals) for pending requests.
2. Approve or reject the request.
3. If approvals are taking too long, check the escalation chain configuration.
4. Consider whether HITL is truly needed for this tool, or if the risk level allows automatic execution.

Tool Returns Unexpected Output

Cause: The tool server returned data that does not match the expected output schema.

Resolution:

1. Check the tool's output schema in the Tool Registry.
2. Review the actual tool response in the Trace Explorer.
3. If the schema is wrong, update it in the Tool Registry.
4. If the tool server is returning incorrect data, debug the tool server.

Tool Server Unreachable

Cause: The MCP endpoint is not responding.

Resolution:

1. Verify the tool's MCP endpoint URL in the registry.
2. Check that the tool server is running and accessible from the MCP Gateway.
3. Review network connectivity and firewall rules.
4. Check the tool server's logs for errors.
5. If the tool server is down, the agent will receive a timeout error.

Agent Cannot Discover a Tool

Cause: The tool is not in the agent's grant list and dynamicDiscovery is false (the default).

Resolution:

1. This is expected behavior. Tools must be explicitly granted.
2. To grant the tool, go to the Agent Designer > Tools tab and add it.
3. Only enable dynamicDiscovery: true if you specifically want the agent to find tools on its own (not recommended for production).

Related Documentation

• Builder Access Control Guide -- Full access control model including tool grants (Dimension 2)
• Registering Agents Guide -- How to create agents that use tools
• Getting Started Guide -- Initial setup and environment configuration
• Troubleshooting Guide -- Additional troubleshooting for common issues
• Architecture Reference -- Platform layer details (L5 MCP Gateway)
• Access Control Reference -- Technical access control specification