Skip to content
Nappai Documentation

MCP Connection

The MCP Connection component lets you link your Nappai dashboard to an MCP (Machine Control Platform) server. Once connected, you can run tools that live on that server, send commands, and receive results back into your workflow.

How it Works

When you drop this component into a flow, it first needs a credential that tells it where the MCP server is and how to authenticate. After you select the credential, you configure the transport method (STDIO or HTTP) and optionally provide a script path or JSON server configuration. The component then opens a connection to the MCP server, sends the chosen tool request, and returns the tool’s output as a message or a tool object that can be used by other components or agents.

Inputs

Mapping Mode

This component has a special mode called Mapping Mode. When you enable this mode using the toggle switch, an additional input called Mapping Data is activated, and each input field offers you three different ways to provide data:

  • Fixed: You type the value directly into the field.
  • Mapped: You connect the output of another component to use its result as the value.
  • Javascript: You write Javascript code to dynamically calculate the value.

This flexibility allows you to create more dynamic and connected workflows.

Input Fields

The following fields are available to configure this component. Each field may be visible in different operations:

  • Command/Script Path: Path to a Python script or command for STDIO transport (e.g., server.py, python server.py). This tells the component what program to run when using STDIO.
  • Environment Variables: Environment variables for STDIO (e.g., DEBUG=true). These are passed to the script when it starts.
  • HTTP Headers: Headers for HTTP transports (authentication, etc.). Use this when the MCP server is accessed over HTTP.
  • Mapping Mode: Enable mapping mode to process multiple data records in batch. When turned on, the Mapping Data input appears.
  • Transport Mode: Select the FastMCP transport method. Choose between STDIO or HTTP depending on your server setup.
  • Server Configuration: JSON configuration for a FastMCP in‑memory server. Provide any custom settings needed for the server.
  • Tool: Required. Select the tool to execute on the MCP server. This is the main action the component will perform.
  • Tool Name: The name of the tool that will be used when this component is connected as a tool. This name will be displayed to the agent when it selects tools to use.
  • Tool Description: A detailed description of what this tool does. This description will help the agent understand when and how to use this tool effectively.
  • Tools arguments metadata: Defines the arguments metadata for the tools. This tells the agent what arguments the tool expects.

Credential
This component requires a credential of type MCP Remote server.

  1. First, configure the credential in the Credentials section of Nappai.
  2. Then, select that credential in the Credential field of this component.
    The credential contains the MCP Server auth, MCP Server url, and MCP api key, but these fields are not shown in the component’s input list.

Outputs

  • Data: A Message (method: perform_action) that contains the raw result returned by the MCP tool. You can feed this into other components that process or display data.
  • Tool: A Tool (method: to_toolkit) that represents the executed tool. This can be passed to an agent or another tool‑handling component.

Usage Example

  1. Set up the credential
    In the Nappai Credentials area, create a new MCP Remote server credential. Enter the server URL, authentication type, and API key.

  2. Add the MCP Connection component
    Drag the component into your flow.

    • Select the credential you just created.
    • Choose Transport Mode → STDIO.
    • Enter server.py in Command/Script Path.
    • Add any required Environment Variables (e.g., DEBUG=true).
    • Pick the tool you want to run from the Tool dropdown (e.g., GetWeather).
    • Provide a friendly Tool Name and Tool Description so agents know what it does.

  3. Connect outputs

    • Link the Data output to a Print component to see the tool’s result.
    • Or connect the Tool output to an Agent component so the agent can decide to use this tool.

  4. Enable Mapping Mode (optional)
    If you want to run the tool on many records at once, toggle Mapping Mode on. Then, for each input field, choose Mapped and connect the corresponding data from a previous component. The component will automatically iterate over the data set.

  • MCP Remote Server Credential – Manage the authentication details needed for this component.
  • Agent – Use the tool output to let an AI agent decide when to call the tool.
  • Print – Display the raw data returned by the MCP tool.

Tips and Best Practices

  • Keep the Command/Script Path simple and test it locally before adding it to the flow.
  • Use Environment Variables to store secrets instead of hard‑coding them in the script.
  • When using HTTP Headers, include any required authentication tokens.
  • Enable Mapping Mode only when you need to process a batch of records; otherwise, use the default single‑record mode for faster execution.
  • Always verify the Tool Description so agents can choose the right tool for the task.

Security Considerations

  • Store the MCP server credentials in the Nappai Credentials area; never expose API keys or passwords in the component’s inputs.
  • If the MCP server is accessed over HTTP, ensure the connection is secured with TLS to protect data in transit.
  • Limit the permissions of the MCP API key to only the tools and actions required for your workflow.