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
• 🔐 Built-in Authentication: IMS token validation and API key support
• 📚 Production Ready: Error handling, logging, and CORS included

Quick Start

Prerequisites

• Node.js 18+
• 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 tempalte generator-app-remote-mcp-server-generic listed in the all tempaltes list
aio app init

Deploy & Use

cd my-mcp-server
aio app use <your-workspace-config.json>
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://<namespace>.adobeioruntime.net/api/v1/web/<xyz>/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

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.