Using MCP server and client in N8N

Note

For MCP server and client interaction, production webhooks are not published in API Cloud. However, TID token validation with scopes is still enforced. Refer to Webhook Access for more details.

Creating a MCP Server

Follow these steps to create and configure an MCP server in N8N:

Step 1: Add MCP Server Trigger Node

Open your N8N workflow and add the MCP Server Trigger node. This node will listen for MCP events and serve as the entry point for your MCP server.

Step 2: Configure the MCP Server Trigger

Click on the MCP Server Trigger node to open its configuration panel. You’ll need to configure the following parameters:

MCP URL Configuration

The MCP Server Trigger will provide two URL options:

• Test URL: Used for testing during development
• Production URL: Used when running using a webhook API

The URL will follow this format:

https://flows-webhook.stage.trimble-ai.com/mcp/agentic/n8n-server/v1/{{workflowId}}

Path Configuration

The path field should be pre-fixed with /agentic/n8n-server/v1/{{workflowId}} where:

• {{workflowId}} is automatically populated with your workflow’s unique identifier
• This path structure ensures proper routing and identification of your MCP server

Step 3: Set Authentication

In the Authentication dropdown, you must set the Authentication to None. The MCP production webhook is protected by TID Token outside of the N8N flow.

Step 4: Connect Your Tool Nodes

After configuring the MCP Server Trigger, connect it to your tool nodes (such as Calculator, as shown in the example). The MCP Server will expose these tools as available functions that can be called by MCP clients.

Step 5: Execute and Test

Once your workflow is configured:

1. Click the Execute step button to test your MCP server locally
2. For prototyping using API, activate your workflow and use the production URL without needing to click the execute button

The MCP Server will now listen for incoming MCP events and route them to the appropriate tool nodes based on the client’s requests.

Creating an AI Agent with MCP Client

This section demonstrates how to create an AI Agent that can interact with MCP servers to access external tools and services. There are two distinct workflow approaches: using the built-in chat node for development/testing and using a webhook for external API integration.

Different Workflows

The Chat Node and Webhook approaches require separate workflows with different AI Agent configurations. Choose the approach that best fits your use case.

Key Differences Between Approaches

Aspect	Chat Node Approach	Webhook Approach
Use Case	Development & Testing	Prototyping External Environment
Trigger	Built-in chat interface	External API calls
TID Token	Generated via HTTP request	Extracted from request header
AI Agent Config	References chat input	References webhook data
Response	Displayed in chat panel	Returned via webhook response
Activation	Manual execution	Always active when deployed

Prerequisites

For Chat Node Approach

Before creating MCP client workflows using the Chat Node approach, you need to set up authentication credentials:

Create TID Application with Client Credentials

1. Register an Application in Trimble Identity:

• Navigate to the Trimble Identity developer portal
• Create a new application with Client Credentials grant type
• Note your Client ID and Client Secret

2. Configure Required Scopes:

• Ensure your application has the necessary scopes
• For MCP operations, include Agentic-N8N-Webhook scope

3. Store Credentials Securely:

• Save your Client ID and Client Secret in N8N credentials
• These will be used for the Basic Auth configuration in the tid_token node

For detailed instructions, follow the TID Client Credentials Grant Flow guide.

For Webhook Approach

The webhook approach has simpler prerequisites:

1. Calling Application Requirements:

• The application calling your webhook must have a valid TID token
• The token must include the Agentic-N8N-Webhook scope
• The token should be passed in the Authorization header

2. No Client Credentials Needed:

• You don’t need to create your own TID application
• Authentication is handled by the calling application

Approach 1: Chat Node-Based Development

This approach is ideal for development and testing of your MCP client workflow.

Chat Node Workflow Overview

This development workflow consists of:

1. When chat message received: Built-in trigger for testing
2. tid_token: Retrieves authentication token using client credentials
3. set TID Token: Stores the token as a variable
4. AI Agent: Processes messages with chat-specific configuration
5. MCP Client: Handles MCP server communication

Step 1: Configure Chat Message Trigger

Use the “When chat message received” node as your workflow trigger. This built-in node provides:

• A simple chat interface for testing
• Direct message input without external dependencies
• Quick iteration during development
• Immediate feedback and debugging capabilities

The chat node automatically provides the user’s message in the workflow context, making it easy to test different scenarios.

Step 2: Set Up TID Token Authentication

Configure the tid_token node to retrieve the authentication token using your client credentials:

Key configurations:

• Method: POST
• URL: https://stage.id.trimblecloud.com/oauth/token
• Authentication: Generic Credential Type
• Generic Auth Type: Basic Auth (using your Client ID and Client Secret from prerequisites)
• Send Headers: Enable to include authorization headers
• Body Parameters: Include grant_type and scope as per the Client Credentials flow

This configuration implements the TID Client Credentials Grant Flow to obtain an access token with the necessary scopes for MCP operations.

Step 3: Set TID Token Variable

Configure the set TID Token node to store the authentication token:

This node extracts the TID token from the authentication response and sets it as a variable for use throughout the workflow.

Step 4: Configure the AI Agent Node

The AI Agent node is the core component that processes chat messages and orchestrates MCP client interactions:

Configure the following parameters:

1. Source for Prompt: Define below

2. Prompt (User Message):

   {% raw %}{{ $('When chat message received').item.json.chatInput }}{% endraw %}

3. Chat Model: Select Trimble Model Gateway

4. MCP Client Integration: Configure in the Options section

Step 5: Configure MCP Client

Set up the MCP Client node to handle communication with MCP servers:

MCP Client Configuration:

1. Credential Type: Configure to use “Bearer Auth” credential

2. Bearer Token: Reference the TID token from the variable set in Step 3:

   {% raw %}{{ $json.tid_token_value }}{% endraw %}

3. Authorization Header: The node automatically formats the token with “Bearer” prefix for API calls

The MCP Client will use this authentication to securely communicate with MCP servers and access their tools.

Step 6: Test the Workflow

1. Click the chat icon in the bottom panel
2. Type a test message (e.g., “What is 5+5”)
3. Monitor execution in the logs panel
4. Review the response

Approach 2: Production Webhook-Based Development

This approach is for prototyping using an API where external applications need to interact with your MCP client.

Webhook Workflow Overview

This webhook workflow shows:

1. Webhook: Receives external API requests
2. set TID Token from header: Extracts TID token from Authorization header
3. AI Agent1: Processes messages with webhook-specific configuration
4. Trimble Model Gateway1: Handles model interactions
5. MCP Client1: Manages MCP server communication

TID Token in Webhook Approach

In this method, the Webhook is already protected by TID, so you don’t need to create client credentials. The calling application provides the TID token in the Authorization header. You simply extract this header and set it as a TID Token variable. Remember: The Token should have Agentic-N8N-Webhook scope in it. Pass down the token to the MCP Client.

Step 1: Configure Webhook Trigger

Set up the Webhook node to receive external requests:

Key configurations:

1. Webhook URLs: The node provides both Test URL and Production URL
2. HTTP Method: Set to POST
3. Path: Configure your desired endpoint path (e.g., d72c211f-63c4-4e55-b6d2-7bf649963cb8)
4. Authentication: Set to None (authentication is handled via TID token in headers)
5. Respond: Use “Using ‘Respond to Webhook’ Node” to control response

The webhook receives requests with the following structure:

• Headers: Contains the Authorization header with Bearer token
• Body: Contains the user’s chat input and other parameters

{
  "chatInput": "what is 7+7",
  "sessionId": "unique-session-id",
  "userId": "user-identifier"
}

Step 2: Extract TID Token from Header

Configure the set TID Token from header node to extract the token from the Authorization header:

Configuration steps:

1. Mode: Set to “Manual Mapping”
2. Fields to Set: Add a new field named tid_token_value
3. Value: Use the expression to remove the “Bearer ” prefix:

{% raw %}{{ $json.headers.authorization.replace('Bearer ', '') }}{% endraw %}

This extracts the raw token from the Authorization header (which comes in the format Bearer eyJhbGciOi...) and stores it in the tid_token_value variable for use by the MCP Client.

Step 3: Configure AI Agent for Webhook Input

Configure the AI Agent node to process webhook requests:

Key configurations:

1. Source for Prompt (User Message): Set to “Define below”

2. Prompt (User Message): Use the expression to read from webhook body:

   {% raw %}{{ $('Webhook').item.json.body.chatInput }}{% endraw %}

3. Chat Model: Configure to use Trimble Model Gateway

4. Tool Integration: The AI Agent connects to the MCP Client for tool access

Step 4: Configure MCP Client

Set up the MCP Client node with proper authentication:

The MCP Client configuration:

1. Credential: Uses “Bearer Auth” credential type

2. Bearer Token: References the token extracted in Step 2:

   {% raw %}{{ $json.tid_token_value }}{% endraw %}

3. Authorization Header: Automatically uses the token with “Bearer” prefix for API calls

Step 5: Return Response

Add a Respond to Webhook node at the end to send the AI Agent’s response back to the calling application:

• Connect it after the MCP Client node
• Configure the response format with appropriate status codes
• Include necessary headers for the response