Build an MCP Server

This page is for developers who want to give an Enconvo Agent tools of their own. A custom MCP server exposes tools that an Enconvo Agent can call. Start with a small local server, verify its inputs and result, then add the service-specific work you need. To install a server someone else made, see MCP Servers. To ship your server so it also installs in Codex and Claude Code, package it as a plugin with --template mcp (see Plugin Formats).

Before you start

You need Node.js and npm. This example uses the TypeScript SDK’s 1.x JavaScript API, pinned to 1.29.0. SDK major versions can use different imports and setup; consult the official MCP server guide when choosing another version.

Write a minimal local server

mkdir hello-mcp
cd hello-mcp
npm init -y
npm install @modelcontextprotocol/sdk@1.29.0 zod@3

Save this as server.mjs:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "hello-enconvo", version: "1.0.0" });

server.registerTool("greet", {
  description: "Return a greeting for the supplied name.",
  inputSchema: { name: z.string().min(1).describe("Name to greet") },
}, async ({ name }) => ({
  content: [{ type: "text", text: `Hello, ${name}!` }],
}));

await server.connect(new StdioServerTransport());

A stdio server waits for protocol messages; starting it in a terminal does not display a chat interface. Keep diagnostics on stderr (for example, console.error) because stdout carries MCP protocol messages. The official guide explains this transport requirement.

Connect it to Enconvo

Add the server

Open Settings → MCP Servers and click Add server. Give it a Server name, such as hello-mcp.

Set how it starts

Choose STDIO. In Command, enter node. In Arguments, enter the absolute path of server.mjs. If Enconvo cannot find Node, use its absolute executable path.

Save and check it

Click Save. Confirm the server connects and exposes greet.

Try it

Make it available to your Agent and ask it to greet “Ada.” The expected tool result is Hello, Ada!.

Equivalent configuration:

{
  "command": "node",
  "args": ["/absolute/path/to/hello-mcp/server.mjs"]
}

Replace the example path with your file’s actual path.

Design useful tools

Give each tool a specific action and description.
Validate input at the tool boundary and return useful error messages.
Separate reading data from mutations such as sending or deleting.
Return a compact result that the Agent can interpret.
Keep credentials in the server’s appropriate configuration, outside source examples and logs.

Remote servers and authentication

For a remote server, use the HTTP or SSE transport offered by its setup instructions and the corresponding Enconvo form (HTTP or SSE instead of STDIO). The server URL must be the MCP endpoint rather than an ordinary website URL. Complete any supported authorization flow and confirm the connection before enabling its tools. Remote transport, authentication discovery, and session behavior depend on the server and protocol version. Use the official SDK and protocol documentation for implementation details rather than inventing an auth manifest that Enconvo does not consume.

Troubleshooting

Problem	What to do
Process exits immediately	Check the executable path, dependencies, syntax errors, and stderr
Connected but no tool appears	Check the tool’s registration, that the tool is enabled, and the selected Agent
Invalid protocol response	Look for accidental stdout logging, or the wrong program being launched
Schema validation error	Compare the actual input shape with the SDK version you use
Remote connection failure	Check the endpoint URL, transport, authentication, and network access

For exposing Enconvo’s own documents to another AI client, use the built-in Knowledge Base MCP server; a custom server is not required.

MCP Servers

Install and manage MCP servers in Enconvo

Plugin Formats

Package a server as a plugin for Enconvo, Codex and Claude Code

Build plugins

Local API and CLI

Deep dives

Before you start

Write a minimal local server

Connect it to Enconvo

Design useful tools

Remote servers and authentication

Troubleshooting

MCP Servers

Plugin Formats

​Before you start

​Write a minimal local server

​Connect it to Enconvo

​Design useful tools

​Remote servers and authentication

​Troubleshooting

​Related

MCP Servers

Plugin Formats

Before you start

Write a minimal local server

Connect it to Enconvo

Design useful tools

Remote servers and authentication

Troubleshooting

Related