Serverless MCP Backend for OpenProject via Netlify Express

Access Point for MCP Consumers: https://gilded-fudge-69ca2e.netlify.app/mcp (Note: This URL serves the MCP endpoint, not for direct browser navigation).

Introduction to this Orchestration Layer

This repository furnishes a Model Context Protocol (MCP) service layer, constructed using the Express framework and operationalized as a Netlify Edge Function. Its primary function is to empower autonomous agents (such as those powered by Langflow, Claude, or Cursor) with the capability to execute Create, Read, Update, and Delete (CRUD) operations against a privately hosted OpenProject installation.

Key technical capabilities demonstrated include: - Initialization of the MCP fabric utilizing the @modelcontextprotocol/sdk. - Seamless interfacing with the external OpenProject RESTful API. - Zero-downtime, serverless deployment architecture leveraging Netlify Functions. - Robust management of proprietary configuration details via Netlify environment variables. - Establishment of a conduit for external, stateful SSE clients (e.g., cloud-based Langflow instances) to interact with the stateless Netlify environment, achieved via the mcp-proxy utility and ngrok tunneling.

• Official Model Context Protocol Specification
• Netlify Functions Documentation

Available OpenProject Manipulators (Tools)

The server exposes the subsequent functional modules for interacting with OpenProject data structures:

• Project Artifacts Management:
  • openproject-create-project: Instantiates a new venture/project.
  • openproject-get-project: Fetches detailed attributes for a specified project identifier.
  • openproject-list-projects: Retrieves an enumerated collection of all ventures (pagination supported).
  • openproject-update-project: Modifies extant project specifications.
  • openproject-delete-project: Removes a designated project entity.
• Work Package (Task) Resource Handling:
  • openproject-create-task: Records a new item of work within a defined project context.
  • openproject-get-task: Retrieves the state of an individual work package.
  • openproject-list-tasks: Enumerates work packages, allowing for project-based filtering (pagination supported).
  • openproject-update-task: Applies modifications to an active task (requires concurrency control via lockVersion).
  • openproject-delete-task: Decommissions a specified work package.

Necessary Prerequisites

To successfully operate this solution, ensure the following components are present:

• Runtime Environment: Node.js (v18 or newer highly recommended).
• Package Manager: npm.
• CLI Tool: Netlify CLI (npm install -g netlify-cli).
• Python Environment: Python 3.10 or a newer variant (essential for the mcp-proxy component used in SSE bridging).
• Python Package Manager: pip.
• Target Instance: Operational OpenProject deployment URL.
• Authentication Credential: A valid OpenProject API Access Token.
• Optional Tunneling: An active ngrok subscription and installed CLI for facilitating remote testing of SSE connections.

Deployment Protocol

1. Source Code Retrieval: bash git clone git@github.com:jessebautista/mcp-openproject.git cd mcp-openproject

2. Node Dependency Resolution: bash npm install

3. Python Bridge Utility Installation: (Verify your primary Python interpreter version is 3.10+) bash # Example for installing via a specific Python version executable: python3.10 -m pip install mcp-proxy # Alternative modern installation method: # pipx install mcp-proxy

Local Environment Configuration and Testing

1. Secret Configuration File Generation:

   • Instantiate a file named .env at the repository root.

   • Populate it with your sensitive deployment parameters: dotenv OPENPROJECT_API_KEY="Your_Secret_API_Credential" OPENPROJECT_URL="https://your.private.openproject.domain.com" OPENPROJECT_API_VERSION="v3"

   • (Security Mandate): Confirm that the .env file is explicitly excluded from version control via inclusion in your .gitignore.

2. Initiate Local Server Emulation:

   • This command launches the local development server, loads environment variables from .env, and exposes the function handlers. bash netlify dev

   • The locally accessible MCP interface will generally resolve to http://localhost:8888/mcp.

3. Validation via MCP Inspector (Separate Session):

   • In an unrelated terminal window, invoke the MCP Inspector, directing its remote connection pointer to your local service: bash npx @modelcontextprotocol/inspector npx mcp-remote@next http://localhost:8888/mcp

   • Navigate to the Inspector's web interface (typically port 6274).

   • Establish the connection, then navigate to the "Tools" pane to rigorously test all enumerated OpenProject manipulation functions.

Production Deployment onto Netlify Infrastructure

1. Configure Environment Secrets in Netlify Portal:

   • Navigate to the site configuration dashboard on Netlify (https://app.netlify.com/sites/gilded-fudge-69ca2e/configuration/env).
   • Under the "Environment variables" section, input the following keys (ensure they are configured for execution within "Functions"):
     • OPENPROJECT_API_KEY: Your OpenProject security token.
     • OPENPROJECT_URL: The URL of your OpenProject deployment (e.g., https://project.corp-domain.net).
     • OPENPROJECT_API_VERSION: Set to v3.
   • (Security Check): The logic within netlify/mcp-server/index.ts accesses these via process.env. Verification that hardcoded values are absent is crucial.

2. Trigger Build and Deployment via Git Flow:

   • Stage modifications: bash git add . git commit -m "Production push: OpenProject MCP service updates"

   • Push changes to the branch Netlify monitors for automated deployment (e.g., main): bash git push origin main

   • Netlify will automatically initiate the build/deploy sequence. Monitor the status under the "Deploys" tab of your Netlify portal.

Post-Deployment Verification

1. Using MCP Inspector Against Live Service:

   • Execute the inspector, referencing the public Netlify endpoint: bash npx @modelcontextprotocol/inspector npx mcp-remote@next https://gilded-fudge-69ca2e.netlify.app/mcp

   • Verify tool functionality via the Inspector UI. Consult Netlify function logs for troubleshooting if connection failures arise.

2. Establishing Remote SSE Client Linkage (e.g., Cloud Langflow Deployment):

   • Because Netlify functions are inherently stateless and do not sustain native long-lived GET/SSE sessions, a proxy layer is mandatory for clients like Langflow that demand SSE. We utilize the Python mcp-proxy in conjunction with mcp-remote and an ngrok public tunnel.

   • Phase A: Activate the Local Proxy Adapter:

     • Execute this command locally (ensure Python 3.10+ is active and mcp-proxy is installed): bash # Configure the proxy to listen on port 7865, using npx mcp-remote as the backend target mcp-proxy --sse-port 7865 -- npx mcp-remote@next https://gilded-fudge-69ca2e.netlify.app/mcp

     • Keep this console session active. Confirm output shows successful binding and invocation of the npx process.

   • Phase B: Generate a Public Access Path via ngrok:

     • In a second, distinct console session, expose the local proxy port: bash ngrok http 7865

     • Capture the public HTTPS address provided by ngrok (e.g., https://<unique-hash>.ngrok-free.app). Copy this entire URL.

   • **Phase C: Configure the External Agent (Langflow):

     • Within the Langflow MCP Connection component (assuming use of https://lang.singforhope.org/):
       • Select Connection Mode: SSE
       • Input MCP SSE URL: Paste the complete ngrok HTTPS address, appending the required /sse suffix for the proxy (e.g., https://<unique-hash>.ngrok-free.app/sse).
     • Successful configuration allows Langflow to communicate with the deployed Netlify service through the chain: ngrok -> mcp-proxy -> mcp-remote -> Netlify Function.

   • (Note): The ngrok configuration serves as a potent mechanism for development verification. For sustained, production-grade connectivity, deployment of the mcp-proxy bridge onto a dedicated, persistent public server is advisable.

Netlify Routing Manifest (netlify.toml)

Confirm that your configuration file appropriately directs ingress traffic targeting the /mcp path to your Express function handler:

toml [[redirects]] force = true from = "/mcp/*" # Catches all potential sub-routes under /mcp status = 200 to = "/.netlify/functions/express-mcp-server"

[[redirects]] # Also ensures the root /mcp path resolves correctly force = true from = "/mcp" status = 200 to = "/.netlify/functions/express-mcp-server"

(Adjust the function name express-mcp-server if your Netlify function file is named differently.)