feat(server): MCP server with actions as tools #4012

kaposke · 2025-05-08T15:35:59Z

Description

This PR adds basic MCP support for executing action. It's basic support for the latest "Streamable Http", and implemented in a stateless manner (based on their example).

This means every message creates a new instance of an McpServer and StreamableHttpServerTransport. This way no connection management is required and it should be scalable out of the box.

Any given call requires a connection-id. The tools available to the caller are the respective active actions of that connection-id.

Testing

I'll be creating a repo with a working example of a client implementation using vercel's AI SDK.
Otherwise, an easy way to test is by installing Claude for Desktop and setting up your mcp servers on: /Users/<your-user>/Library/Application Support/Claude/claude_desktop_config.json with this format:

{
  "mcpServers": {
    "nango-google-drive": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:3003/mcp",
        "--header",
        "Authorization:<your-secret-key>",
        "--header",
        "provider-config-key:google-drive",
        "--header",
        "connection-id:<your-connection-id>"
      ]
    }
  }
}

Don't add spaces to the headers

MCP Server Implementation with Actions as Tools

This PR adds Model Context Protocol (MCP) support to Nango's server, allowing AI assistants to discover and execute Nango actions as tools. The implementation follows a stateless approach where each request creates new server instances, avoiding shared state issues. Actions are exposed as MCP-compatible tools with their schemas automatically converted from Nango's format, enabling seamless interaction between AI models and Nango integrations.

Key Changes:
• Added new /mcp endpoint with authentication and connection validation
• Implemented stateless MCP server that maps Nango actions to MCP tools
• Created schema conversion logic to transform action inputs to MCP-compatible formats
• Added action execution handler that processes tool calls and returns structured results

Affected Areas:
• Server API endpoints and routing
• Action retrieval and execution flow
• Server dependencies (added @modelcontextprotocol/sdk)
• Type definitions for MCP requests/responses

Potential Impact:

Functionality: Enables AI assistants to discover and execute Nango actions through the MCP protocol, expanding integration capabilities for LLM-based applications

Performance: Minimal impact as the implementation follows a stateless pattern that creates isolated server instances per request, avoiding shared state issues

Security: Leverages existing authentication mechanisms and validation for connections, maintaining security boundaries

Scalability: The stateless approach should scale well by avoiding session management overhead

Review Focus:
• Stateless implementation approach for handling MCP requests
• Schema conversion logic between Nango actions and MCP tools
• Error handling and compliance with MCP protocol specifications
• Response formatting and result serialization

Testing Needed

• Test with Claude desktop client to verify discovery and execution of tools
• Verify schema conversion handles complex action input types correctly
• Test error cases (invalid connections, actions, authentication)
• Test concurrent requests to ensure isolated handling

Code Quality Assessment

packages/server/lib/controllers/mcp/server.ts: Well-structured implementation with proper error handling using Result pattern. Good separation of concerns between tool conversion, request handling, and execution.

packages/server/lib/controllers/mcp/mcp.ts: Clean request validation and handler implementation. Follows MCP protocol specifications for response formatting.

Best Practices

Error Handling:
• Uses Result pattern for robust error management
• Validates inputs before processing

Security:
• Leverages existing authentication mechanisms
• Validates connections before exposing actions

Code Organization:
• Clear separation between protocol handling and business logic
• Type-safe implementation

Possible Issues

• Complex action schemas might not convert perfectly to MCP tool schemas
• Error responses might need refinement as MCP protocol evolves
• Each request creates new server instances which could be optimized in the future

This summary was automatically generated by @propel-code-bot

linear · 2025-05-08T15:36:02Z

NAN-3102 MCP prototype

cubic-dev-ai · 2025-05-08T15:36:03Z

Your mrge subscription is currently inactive. Please reactivate your subscription to receive AI reviews and use mrge.

…mcp-server

kaposke · 2025-05-14T20:50:54Z

packages/server/lib/controllers/mcp/server.ts

+            .setTag('nango.providerConfigKey', providerConfig.unique_key);
+
+        const logCtx = await logContextGetter.create(
+            { operation: { type: 'action', action: 'run' }, expiresAt: defaultOperationExpiration.action() },


Perhaps we add something to indicate this comes from MCP?

we'll probably need at some point. I think it is ok without it for now

TBonnin

Thank you. my main concern is about creating a mcp server for each instance

TBonnin · 2025-05-15T13:28:29Z

packages/server/lib/controllers/config.controller.ts

@@ -172,7 +172,7 @@ class ConfigController {
                };
            });

-            const actions = await getActionsByProviderConfigKey(environmentId, providerConfigKey);
+            const actions = await getSimplifiedActionsByProviderConfigKey(environmentId, providerConfigKey);


I don't really follow why this change is about?

There's an existing getActionsByProviderConfigKey which is exactly what I need, except it strips everything and just leaves the sync_name (renamed as name). I didn't want to modify it because it's used in some payloads and I want to avoiding breaking anything unrelated. But it's annoying because it takes exactly the function name that I needed.

I could name my function something else, but I would expect getActionsByProviderConfigKey to give me the full action, not a modified and stripped down version of it, so I decided to rename the existing function instead.

TBonnin · 2025-05-15T13:29:41Z

packages/server/lib/controllers/mcp/mcp.ts

+            res.status(500).json({
+                jsonrpc: '2.0',
+                error: {
+                    code: -32603,


what does this code come from?

https://modelcontextprotocol.io/docs/concepts/architecture#error-handling

can we add a comment with this link to easily find it in the future?

TBonnin · 2025-05-15T13:29:52Z

packages/server/lib/controllers/mcp/mcp.ts

+                jsonrpc: '2.0',
+                error: {
+                    code: -32603,
+                    message: 'Internal server error'


should we return more details about the error?

Replaced by the Result pattern and added context.

TBonnin · 2025-05-15T13:30:22Z

packages/server/lib/controllers/mcp/mcp.ts

+    }
+});
+
+// We have to be explicit about not supporting SSE


is that part of the protocol?

Yes. The client may attempt to open an SSE stream on this endpoint, and we have to respond.

TBonnin · 2025-05-15T13:32:00Z

packages/server/lib/controllers/mcp/server.ts

+import type { Span } from 'dd-trace';
+import type { JSONSchema7 } from 'json-schema';
+
+export async function createMcpServerForConnection(account: DBTeam, environment: DBEnvironment, connection: DBConnectionDecrypted, providerConfigKey: string) {


all new functions should return a Result. It makes error handling more explicit

TBonnin · 2025-05-15T13:35:11Z

packages/server/lib/controllers/mcp/mcp.ts

+    }
+
+    try {
+        const server = await createMcpServerForConnection(account, environment, connection, providerConfigKey);


why create a mcp server instance on each request instead of having one mcp server with logic to fetch actions in the handlers?

Mostly following their advice on their example: https://github.com/modelcontextprotocol/typescript-sdk?tab=readme-ov-file#without-session-management-stateless

// In stateless mode, create a new instance of transport and server for each request
// to ensure complete isolation. A single instance would cause request ID collisions
// when multiple clients connect concurrently.

I am not sold yet on this recommendations but let's see. Good for me for now

TBonnin · 2025-05-15T13:36:11Z

packages/server/lib/controllers/mcp/server.ts

+
+    server.setRequestHandler(ListToolsRequestSchema, () => {
+        return {
+            tools: actions.map(actionToTool).filter((tool) => tool !== null)


you can flatMap instead of map/filter

TBonnin · 2025-05-15T13:39:16Z

packages/server/lib/controllers/mcp/server.ts

+            .setTag('nango.providerConfigKey', providerConfig.unique_key);
+
+        const logCtx = await logContextGetter.create(
+            { operation: { type: 'action', action: 'run' }, expiresAt: defaultOperationExpiration.action() },


we'll probably need at some point. I think it is ok without it for now

TBonnin · 2025-05-16T13:06:36Z

packages/server/lib/controllers/mcp/mcp.ts

+
+    if (error || !connection) {
+        res.status(400).send({
+            error: { code: 'unknown_connection', message: 'Provided ConnectionId and ProviderConfigKey does not match a valid connection' }


Suggested change

error: { code: 'unknown_connection', message: 'Provided ConnectionId and ProviderConfigKey does not match a valid connection' }

error: { code: 'unknown_connection', message: 'Provided ConnectionId and ProviderConfigKey do not match a valid connection.' }

tip: I find llms are pretty good at copy-writing and fixing my unperfect english

khaliqgant

From a usage perspective, tested and works well! Nice work

TBonnin

works well with my dummy actions locally.
Please rebase with master and address the comments (especially about logging for actions that doesn't have to be done on server).
Otherwise you are good to go

prototype working stateless MCP server with actions as tools

ebe828c

kaposke added 2 commits May 14, 2025 10:42

add modelcontextprotocol sdk

84c3b9c

Merge remote-tracking branch 'origin/master' into gui/NAN-3102/nango-…

5ca654a

…mcp-server

kaposke marked this pull request as ready for review May 14, 2025 20:41

kaposke commented May 14, 2025

View reviewed changes

kaposke requested a review from a team May 14, 2025 20:51

TBonnin reviewed May 15, 2025

View reviewed changes

address comments

c3ec498

TBonnin reviewed May 16, 2025

View reviewed changes

khaliqgant approved these changes May 16, 2025

View reviewed changes

TBonnin reviewed May 16, 2025

View reviewed changes

kaposke added 5 commits May 16, 2025 12:45

don't report success/failure

48bc04b

Merge branch 'master' into gui/NAN-3102/nango-mcp-server

4ae6a17

Fix error message

c46f349

fix with new async syntax.

9c96d08

fix new triggerAction result

422e6d6

kaposke merged commit 5dcf955 into master May 16, 2025
17 checks passed

kaposke deleted the gui/NAN-3102/nango-mcp-server branch May 16, 2025 17:11

	error: { code: 'unknown_connection', message: 'Provided ConnectionId and ProviderConfigKey does not match a valid connection' }
	error: { code: 'unknown_connection', message: 'Provided ConnectionId and ProviderConfigKey do not match a valid connection.' }

feat(server): MCP server with actions as tools #4012

feat(server): MCP server with actions as tools #4012

Uh oh!

Conversation

kaposke commented May 8, 2025 • edited by propel-code-bot bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Testing

Uh oh!

linear bot commented May 8, 2025

Uh oh!

cubic-dev-ai bot commented May 8, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TBonnin left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

khaliqgant left a comment

Choose a reason for hiding this comment

Uh oh!

TBonnin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

kaposke commented May 8, 2025 •

edited by propel-code-bot bot

Loading