> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enconvo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating Custom MCP Servers

> Build a small local MCP tool and connect it to Enconvo.

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. For installing existing servers, see [MCP setup](/features/mcp).

## A minimal local server

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](https://modelcontextprotocol.io/docs/develop/build-server) when choosing another version.

```sh theme={null}
mkdir hello-mcp
cd hello-mcp
npm init -y
npm install @modelcontextprotocol/sdk@1.29.0 zod@3
```

Save this as `server.mjs`:

```javascript theme={null}
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](https://modelcontextprotocol.io/docs/develop/build-server) explains this transport requirement.

## Connect it to Enconvo

Open **Settings → Plugins → MCP Servers**, add a server, and select **stdio**. Set the command to your Node executable and the argument to the absolute path of `server.mjs`.

Equivalent configuration:

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

Replace the example path with your file's actual path. If Enconvo cannot find Node, use its absolute executable path. Confirm the server connects and exposes `greet`, then make it available to your Agent and ask it to greet “Ada.” The expected tool result is `Hello, Ada!`.

## 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. 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

| Symptom | Check |
| - | - |
| Process exits immediately | Executable path, dependencies, syntax errors, and stderr |
| Connected but no tool appears | Registration, tool enablement, and the selected Agent |
| Invalid protocol response | Accidental stdout logging or launching the wrong program |
| Schema validation error | The actual input shape and SDK version |
| Remote connection failure | 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](/advanced/knowledge-base-mcp); a custom server is not required.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.