From Concept to POC: Integrating MCP Servers with Adobe Experience Manager

AI assistants are becoming more capable by the day—but to truly unlock their potential, they need context. That’s where Model Context Protocol (MCP) servers come in. Think of them as the HTTP for the AI era; just as HTTP standardized how browsers communicate with web servers, MCP standardizes how AI models communicate with external tools and data sources to become context-aware.

The Model Context Protocol (MCP) has taken the AI development world by storm since its introduction by Anthropic in November 2024. What started as an innovative solution to connect AI assistants with external data sources has quickly evolved into a cornerstone technology for modern AI applications. The momentum behind MCP is undeniable.

From GitHub, Figma, MongoDB, Redis, etc., to PayPal, Notion, Stripe, BrowserStack, Azure, everyone is launching their MCP servers. And if a product doesn’t have any yet, we’ll likely find one developed by the community. Today, every other dev tool like Zed, Cursor, Windsurf, Replit, and Postman all provide a way to enhance their functionality via MCP servers.

Anthropic provides a helpful list of MCP Servers, Frameworks for building MCP servers and clients, and other great resources.

There are also fully developed stores for MCP servers and other related tools. Websites like MCP Market , MCP.so , and Glama provide thousands of servers with good documentation and testing details.

 At 3|SHARE, we’ve been exploring what this could mean for Adobe Experience Manager (AEM) as well.

In this post, Ankur walks you through:

• What MCP servers are and why they matter.
• How to build a basic MCP server for AEM.
• A proof of concept (POC) that uses AI agents to manage AEM packages.

Whether you're new to MCP or curious about AI integrations in AEM, this guide is a great place to start.

What is MCP (Model Context Protocol)?

Model Context Protocol (MCP) is an open standard that allows AI applications to connect with external tools, data sources, and services. It functions as a universal bridge that lets AI assistants interact with your local files, databases, APIs, and other resources in a consistent and standardized manner.

We can think of MCP like a USB-C port for AI applications. Just as USB-C offers a unified way to connect devices with various accessories and peripherals, MCP provides a standardized way to connect AI models to different data sources and tools. This empowers AI to go beyond conversations and take real-world actions through defined APIs, such as making a purchase on Amazon or creating a branch in a GitHub repository.

How is it different from AI Agents?

AI Agents are autonomous AI systems that can think and reason about problems, make decisions based on context and goals, and plan multi-step actions to achieve objectives without constant human guidance. Think of it this way: AI Agents are like skilled chefs who can think, plan, and make decisions, while MCP is like the kitchen equipment that gives the chef access to ingredients and tools.

So, AI agents and MCP can work together to create powerful AI experiences.

Why MCP?

MCP helps you build agents and complex workflows on top of LLMs. Before MCP, each AI application had to build custom integrations for every tool or service. MCP standardizes this process, making it easier for developers to create powerful AI workflows without reinventing the wheel. For users, this means AI assistants can become much more capable, helping with actual work tasks rather than just providing information.

How MCP Works: The Big Picture

MCP uses a client-server architecture:

• MCP Client: The AI application (like Claude Desktop, Postman, Cursor, Zed, n8n, etc.).
• MCP Server: A program that provides specific capabilities.
• Communication: They talk using a standardized protocol.
• Message Format: JSON-RPC 2.0.
• Transport Types: Standard Input/Output (stdio) or Streamable HTTP.

Core MCP Concepts

Tools

Tools are functions that an MCP server provides that the AI can call. In our example, list-packages, upload-package, install-package, etc., are tools. Each tool should:

• Have a clear and descriptive name.
• Include a docstring explaining what it does.
• Handle errors gracefully.
• Return meaningful results.

Resources

Resources are data sources the MCP server can provide, like files, database records, or API responses. They’re identified by URIs and can be read by the AI client.

Prompts

Prompts are reusable templates your server can provide to help users interact with your tools more effectively.
For the sake of simplicity, we’ll focus on Tools in our AEM MCP server.

Configuring our own AEM MCP server

Anthropic provides SDKs in multiple languages to create MCP servers. There are other 3rd-party frameworks also, but to keep things simple, we’ll use Anthropic’s TypeScript SDK to create our AEM MCP server.

Prerequisites

1. A running AEM instance.
2. Basic understanding of REST APIs.
3. Claude Desktop app.
4. Latest Node.js LTS.
5. Basic familiarity with JavaScript/TypeScript.

💡 Note: JavaScript/TypeScript is not required to create MCP servers — we’re using the MCP TypeScript SDK in this guide, but you can also use other language SDKs like Java, Python, and more.

Let’s dive in!

Clone project

Clone the project from https://bitbucket.org/3SHARE/aem-mcp-server/src/main/.

Project structure

• The aem-mcp-server is a node project which uses:
  • TypeScript and tsx (TypeScript Execute).
  • @modelcontextprotocol/sdk - MCP TypeScript SDK.
  • Zod - data schema validation library.
  • node-fetch - for executing HTTP calls.
• aem-package-manager-apis.ts defines the AEM REST APIs for listing, uploading, installing, uninstalling, and deleting content packages from AEM.
• index.ts creates the MCP server and defines tools corresponding to each AEM REST API.

Build project

In the project directory, execute:npm install && npm run build. This will install the dependencies and compile the TS files. The compiled JS will be created under the dist directory.

Code Explanation

aem-package-manager-apis.ts

• This is a simple TypeScript file that has no code related to the MCP server itself.
• It exports 5 utility functions to perform content package operations on an AEM server.
  1. listPackages
  2. uploadPackage
  3. installPackage
  4. uninstallPackage
  5. deletePackage
• The AEM server connection details will be retrieved from the environment variables, or defaults will be used. The environment variables can be configured in the Claude Desktop config file, specifically for our MCP server.

index.ts

• This is the main file that creates the MCP server using the MCP TypeScript SDK.

  const server = new McpServer({
    name: "AEM MCP Server",
    version: "1.0.0",
    description: "Adobe Experience Manager Package Management tools for content deployment and maintenance."
  });

• It uses Zod to define the parameter schemas with validation and documentation for our MCP server tools.
  • Zod is a TypeScript-first validation library. Using Zod, we can define schemas that we can use to validate data. It also provides us with options to define metadata for each schema, like a description of a data field. Zod is for TypeScript what Pydantic is for Python.
  • Here is an example of a filePathSchema that we have used for a file path input to upload a content package to AEM. It validates that the file path is not empty, is a zip file, and doesn’t contain a relative path traversal. The describe option will be used to provide more context for the field.

  const filePathSchema = z.string()
    .min(1, "File path cannot be empty")
    .refine(
      (path) => path.endsWith('.zip'), "File must be a .zip package file")
    .refine(
      (path) => !path.includes('..'), "File path cannot contain relative path traversal")
    .describe("Absolute path to the AEM content package file (.zip). Example: /path/to/my-package-1.0.0.zip");
              

• server.tool is used to register an MCP Tool. It accepts a unique tool name, a description to provide context of the tool, a Zod schema to define parameters, and a callback function that will be executed when this tool is called.
  • Here is the signature of our upload-package tool that will take a content package file path, which will be uploaded to the AEM server.

  server.tool("upload-package",
    "Uploads an AEM content package (.zip) from the local filesystem to the AEM Package Manager. The tool validates the package file and transfers it to the AEM instance’s package repository at /etc/packages/. Use this when you have a content package file that needs to be deployed to AEM for installation.",
    { filePath: filePathSchema },
    async ({filePath}) => { /* Implementation code. */ }
  );

• At last, we’ll start our MCP server so it can begin receiving messages on stdin and sending messages on stdout.

  const transport = new StdioServerTransport();
  await server.connect(transport);

Configure Claude Desktop

1. Open Claude Desktop Settings
2. Click on “Developer” in the left-hand bar of the Settings pane, and then click on “Edit Config”.
   
   
    
3. This will create/display a configuration file in your file system at:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\\Claude\\claude_desktop_config.json
4. Open up the configuration file in any text editor.
5. Add the AEM MCP server we have created using:

   {
     "mcpServers": {
       "aem-mcp-server": {
         "command": "node",
         "args": [
           "<parent-directory-path-of-cloned-repo>/aem-mcp-server/dist/index.js"
         ],
         "env": {
           "AEM_HOST": "<http://localhost:4502>",
           "AEM_USERNAME": "admin",
           "AEM_PASSWORD": "admin",
           "AEM_PACKAGE_GROUPS": "my_packages, mcp-group"
         }
       }
     }
   }

6. Replace the environment variables with your AEM server details, if needed.
7. AEM_PACKAGE_GROUPS defines the content package groups with which we want to work. This is needed because AEM has a long list of content packages installed, and a Free Tier version of Claude Desktop doesn’t support that many tokens in the context. Hence, we are only listing content packages from a defined list of groups. Also, in case any of these environment variables are not provided, the app has default values for them in the code.

Demo

Debugging

Anthropic´s official debugging guide provides good information on debugging the MCP servers and their configurations, like checking server and client logs, enabling DevTools on Claude Desktop, etc. But many of those are kind of specific to the Claude Desktop as an MCP client.

A great option to exclusively test an MCP server without even an MCP client is MCP Inspector. Let’s quickly see what it is and how we can use it to test our MCP server.

MCP Inspector

The MCP Inspector is an interactive debugging dashboard for testing MCP servers. Just like web developers use browser developer tools to inspect websites, MCP developers can use MCP Inspector to:

• Test the MCP servers without connecting them to AI clients.
• Debug communication issues between clients and servers.
• Explore the available tools and resources your server provides.
• Validate server responses in real-time.

The Inspector runs directly through npx without requiring any installation:

npx @modelcontextprotocol/inspector <command> <arg1> <arg2>

To run the MCP Inspector for our AEM MCP Server, execute:

npx @modelcontextprotocol/inspector npm start

or

npx @modelcontextprotocol/inspector node dist/index.js

This will help us quickly test the MCP server without an MCP client (Claude Desktop).

Security

Security should be the top priority when building MCP servers. Since these servers often access sensitive data, file systems, databases, and external APIs, a single vulnerability can expose the entire system. We have recently seen an exploit of the official GitHub MCP server.

Here are some of the fundamental security checks every MCP server should implement:

• Input Validation and Sanitization - Malicious or malformed inputs can lead to code injection, path traversal, and system compromise. So, always validate and sanitize input data to prevent injection attacks and malformed data.
• Path Traversal Prevention - Attackers can use ../ sequences to access files outside of intended directories. Always secure file system access and keep it minimal. A well-configured MCP system should follow the principle of least privilege.
• Rate Limiting - Preventing abuse and DoS attacks.
• Authentication & Authorization - Controlling access to server functions.
• Secure Error Handling - Preventing information disclosure.
• Secure Configuration - Managing secrets and settings safely.

Troubleshooting and notes

1. Zod v4 is not supported in the MCP TypeScript SDK at the time of writing this blog.
2. On some machines, we might need to provide the absolute paths for each executable while configuring the MCP server. The errors are not very user-friendly, so in case a well-tested MCP server is having issues while configuring it with a MCP client, try using the absolute paths for all the executables in the client’s config JSON. Check here for more information
3. Local MCP servers should not log messages to stdout (standard out), as this will interfere with protocol operation. Either use stderr, a custom file logger, or the MCP SDK sendLoggingMessage API.

Outro

At 3|SHARE, we’re always exploring new ways to push AEM further—and integrating AI through MCP servers is just one of the exciting frontiers we’re working on. If you’re curious about how AI can enhance your AEM workflows or want to explore custom integrations like the one in this post, we’d love to hear from you.
Let us know what you think, and don’t hesitate to reach out if you’re ready to bring AI into your AEM ecosystem.

Get in touch with us today for an assessment of your MCP+AEM integration!