Skip to content

Custom MCP Servers

Build and connect custom tools using the Model Context Protocol.

What is MCP?#

The Model Context Protocol (MCP) is an open standard for connecting AI assistants to external tools and data sources. LumenFlow supports MCP natively.

Building an MCP server#

An MCP server exposes tools with names, descriptions, and input schemas. When connected, LumenFlow automatically discovers these tools and makes them available to Sidekick. MCP servers can be written in any language that supports MCP. Cloud-hosted connections use public HTTPS.

For details on building MCP servers, see the MCP specification.

Connecting your server#

  1. Deploy your MCP server at a public HTTPS URL. Cloud connects only to public HTTPS endpoints. The URL must not contain credentials, a query string, or a fragment. A stdio or loopback server runs through a connected runner, not on Cloud.
  2. Go to Settings → Connections → Custom MCP
  3. Enter the server URL
  4. LumenFlow discovers available tools automatically
  5. Configure governance rules for each tool

Tool discovery#

When you connect an MCP server, LumenFlow queries it for available tools and their schemas. These appear in Sidekick's tool palette and can be used in conversations.

Per-user OAuth#

Some hosted MCP servers need each person to sign in with their own account. For these, the server uses OAuth 2.1 and each workspace member connects their own account:

  • LumenFlow reads the server's authorization metadata and requires PKCE with the S256 method.
  • Where the server uses dynamic client registration, LumenFlow registers a client and stores it.
  • The authorization request names the server URL as the resource indicator (RFC 8707), so a token is only used for that server.
  • Each token belongs to one member. Disconnecting removes that member's token and leaves other members' connections in place.

Members connect and disconnect from the dashboard.

Remote MCP directory#

The directory lists remote MCP servers that LumenFlow has checked. It is a list of suggestions. Connecting one creates a workspace custom MCP server through the same path as a manual add. The new server is disabled until it passes admission, and its tools follow the read-only rules below. Templates are shown only while their last re-check passes.

Read-only tools#

A tool from an admitted server is treated as read-only only when its declared manifest marks it read-only. Every other tool is treated as consequential and goes through your governance rules.

Best practices#

  • Validate inputs — MCP tools receive user-influenced input
  • Return structured data — JSON responses work best
  • Handle errors gracefully — return error messages, not stack traces
  • Document tools — clear descriptions help Sidekick use them correctly
Success

MCP servers can be written in any language. The protocol uses JSON-RPC. Cloud-hosted connections use public HTTPS.