generator-app-remote-mcp-server-generic

Adobe App Builder template for creating Model Context Protocol (MCP) servers using the official MCP TypeScript SDK and Adobe I/O Runtime.

What is this template?

Generate MCP servers that run on Adobe I/O Runtime. Connect AI assistants like Cursor, Claude Desktop, and other AI tools to your custom functions, data, and prompts through the standardized MCP protocol.

Key Features

• 🔧 Official MCP TypeScript SDK: Built with @modelcontextprotocol/sdk v1.17.4
• 📝 Type Safety: Zod schema validation for all parameters
• 🚀 Serverless Ready: Deploy to Adobe I/O Runtime with auto-scaling
• 🛠️ Complete MCP Implementation: Tools, Resources, and Prompts support
• 🎨 MCP App UI: The weather tool renders an interactive, themed card (via @modelcontextprotocol/ext-apps) instead of plain text, as a starting example for building your own tool UIs
• 🔐 Built-in Authentication: IMS token validation and API key support
• 📚 Production Ready: Error handling, logging, and CORS included

Quick Start

Prerequisites

• Node.js 20.19+, 22.13+, or 24+ for generated-app development (Adobe I/O Runtime target: Node.js 20)
• Adobe I/O CLI: npm install -g @adobe/aio-cli
• Adobe Developer Console project with I/O Runtime enabled

Generate Project

# Using Adobe I/O CLI , You will see template generator-app-remote-mcp-server-generic listed in the all templates list
aio app init

Deploy & Use

cd my-mcp-server
aio app use 
aio app deploy

Connect to your deployed MCP server in Cursor or Claude Desktop using the provided URL.

Claude Desktop Configuration

Add this to your Claude Desktop configuration file:

{
  "mcpServers": {
    "mcp-server-name": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://xxxx.adobeioruntime.net/api/v1/web/your-project/mcp-server"
      ]
    }
  }
}

Cursor configs

{
  "mcpServers": {
    "mcp-server-name": {
      "url": "https://.adobeioruntime.net/api/v1/web//mcp-server",
      "type": "streamable-http"  
   }
  }
}

Example Test prompt

" Hey, Can you please ask #mcp-server-name# about weather in Noida? "

MCP Features

Tools: Interactive functions AI assistants can call (echo, calculator, weather) Resources: Static content access (documentation, data, files)
Prompts: Reusable prompt templates with parameters

All implemented using the official MCP TypeScript SDK

Weather Tool UI

The weather tool doesn’t just return text - it links its result to an ui://weather/mcp-app.html resource via _meta.ui.resourceUri, so MCP Apps-capable hosts render a themed, animated weather card (sun/clouds/rain/snow) instead of a plain response. The UI source lives in actions/mcp-server/app-ui/src/weather/ (HTML/CSS/TypeScript, built with Vite) and is inlined into the deployed bundle at build time (npm run build:ui && npm run embed:ui, run automatically as part of npm run build), since Adobe I/O Runtime only deploys the single webpack bundle. Add more MCP App UIs by dropping a new app-ui/src//.{html,ts,css} - the build scripts pick it up automatically.

Authentication

The generated MCP servers include built-in authentication support to secure your endpoints:

IMS Token Validation (Adobe Users)

Validate Bearer tokens via Adobe IMS userinfo endpoint. Ideal for Adobe employee or partner authentication.

Setup:

# Set in .env or app.config.yaml
AUTH_VALIDATE_IMS=true

Client Configuration (Cursor):

{
  "mcpServers": {
    "my-mcp": {
      "url": "https://namespace.adobeioruntime.net/api/v1/web/pkg/mcp-server",
      "type": "streamable-http",
      "headers": {
        "Authorization": "Bearer YOUR_IMS_TOKEN"
      }
    }
  }
}

Client Configuration (Claude Desktop):

{
  "mcpServers": {
    "my-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://namespace.adobeioruntime.net/api/v1/web/pkg/mcp-server",
        "--header",
        "Authorization:${IMS_TOKEN}"
      ],
      "env": {
        "IMS_TOKEN": "Bearer YOUR_IMS_TOKEN"
      }
    }
  }
}

API Key Authentication (Service-to-Service)

Simple key-based authentication for service-to-service communication.

Setup:

# Set in .env or app.config.yaml
SERVICE_API_KEY=your-secret-key-here

Client Configuration (Cursor):

{
  "mcpServers": {
    "my-mcp": {
      "url": "https://namespace.adobeioruntime.net/api/v1/web/pkg/mcp-server",
      "type": "streamable-http",
      "headers": {
        "x-api-key": "your-secret-key-here"
      }
    }
  }
}

Client Configuration (Claude Desktop):

{
  "mcpServers": {
    "my-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://namespace.adobeioruntime.net/api/v1/web/pkg/mcp-server",
        "--header",
        "x-api-key:${API_KEY}"
      ],
      "env": {
        "API_KEY": "your-secret-key-here"
      }
    }
  }
}

No Authentication (Development Only)

Leave both variables unset for open access during development. Not recommended for production.

Security Best Practices:

• Always enable authentication in production deployments
• Use strong random values for SERVICE_API_KEY
• Never commit secrets to version control
• Rotate API keys regularly

Development

Testing the Generator

# Run unit tests
npm test

# Test end-to-end generation
npm run e2e

Customizing the Template

1. Modify Templates: Edit files in src/templates/
2. Update Generator: Modify src/index.js for prompts/logic
3. Extend Features: Add capabilities in src/templates/actions/mcp-server/tools.js

👥 Contributors

Resources

• 📚 MCP Documentation
• 🔧 MCP TypeScript SDK
• 🏗️ Adobe I/O Runtime
• 📖 App Builder Templates

License

Apache V2 License - see LICENSE for details.