Welcome Pages
Pages are now available as full-screen example templates that showcase real-world use cases and best practices for composing interfaces with the aFP Design System.
Dark Light
System Default LBBW Jira Confluence Source Code
Share Playground

MCP #

The Model Context Protocol (MCP) is a standardized way for AI systems to interact with external services in a controlled and reliable manner. It defines how an AI client can request information or actions from a server without needing direct access to internal code, databases, or infrastructure.

An MCP server provides a clear contract between the AI and the system it interacts with. The AI decides what it wants to achieve, while the MCP server defines which capabilities are available and how they can be used. This separation makes integrations predictable, transparent, and easier to maintain over time.

Unlike ad-hoc integrations or custom prompts, MCP exposes structured tools and resources with well-defined inputs and outputs. This allows AI systems to work with domain-specific knowledge that is not part of their training data, while ensuring that all interactions remain explicit and auditable.

MCP servers can be used in different environments. They can run locally during development, for example inside an IDE, or be hosted as a remote HTTP service for shared or production use cases. In both scenarios, the protocol remains the same, which makes it easy to move from local experimentation to a centralized setup.

In the context of the aFP Design System, the MCP server exposes structured information about available components and their metadata. This enables AI tools to understand the design system, answer questions accurately, and support developers with context-aware assistance based on the current state of the system.

Installation #

The MCP package is fully synchronized with the Design System version to ensure consistency and compatibility across all components.

The aFP Design System MCP server is distributed as an npm package and can be installed as part of an existing Node.js project.

npm install @afp-design-system/mcp

After installation, the server entry points are available in node_modules:

Both servers are based on the same MCP implementation and expose identical capabilities.

The package includes a custom-elements.json manifest that is used by the MCP server as its primary data source. No additional setup is required in the default configuration.

The local server is typically used during development or inside an IDE, while the HTTP server is intended for shared or production environments.

Local Server #

The following example describes the setup for IntelliJ IDEA in combination with GitHub Copilot. Other IDEs with MCP support can be configured in a similar way.

1. Requirements #


2. IntelliJ Settings #

Go to Settings > Editor > Inlay Hints > Code vision and enable the following options:


3. MCP Configuration #

  1. Click the GitHub Copilot icon in the IntelliJ toolbar and open the Copilot chat.
  2. In the chat input, select Agent from the mode selector (default is Ask). An additional settings icon will appear — click it.
  3. In the dialog that opens, click + Add More Tools…. This will open the mcp.json configuration file.
  4. Add or extend the configuration with the following entry and save the file:
{
  "servers": {
    "afp-design-system": {
      "command": "/path/to/node/npx",
      "args": [
        "node",
        "/path/to/node_modules/@afp-design-system/mcp/dist/stdio.js"
      ],
      "env": {}
    }
  }
}

Optional environment variables:


4. Start MCP Server #

  1. Restart IntelliJ and open the mcp.json configuration again as described in step 3.
  2. Select the afp-design-system entry and click Start within the mcp.json editor. IDE MCP Setup
  3. The afp-design-system MCP server should now appear in the list of available MCP servers and be ready for use.

Self-Hosted Server #

The HTTP server variant exposes the MCP server as a network-accessible service. It is intended for shared environments, backend services, or production deployments where multiple clients should access the same MCP instance.

Unlike the local server, which is started as a stdio-based process inside an IDE, the HTTP server runs as a standalone service and can be accessed by multiple clients over the network.

The server can be started directly from the installed npm package:

node /path/to/node_modules/@afp-design-system/mcp/dist/http.js

The server listens on a configurable port (default: 3333) and exposes the MCP endpoint at:

http://localhost:3333/mcp

Optional environment variables:

Example:

PORT=8787 \
MANIFEST_PATH=/path/to/custom-elements.json \
node /path/to/node_modules/@afp-design-system/mcp/dist/http.js

The HTTP server is typically deployed behind a reverse proxy (for example NGINX) and can be secured using standard infrastructure mechanisms such as HTTPS, authentication headers, or network-level access control.

Hosted Server #

The aFP Design System MCP server is available as a centrally hosted HTTP service inside the cluster environment. This allows clients to connect to a managed MCP instance without running their own server process.

The hosted endpoint is available at:

https://design-system-mcp.afp.dev.atlas.adessofinancialplatform.com/mcp

The hosted server exposes the same tools and capabilities as the local HTTP and stdio variants. The protocol and lifecycle remain identical.


Connection Model #

The hosted server uses the Streamable HTTP transport of the Model Context Protocol. Each client must establish its own MCP session before invoking tools.

The lifecycle is:

The session ensures proper lifecycle handling and allows multiple clients to connect concurrently.


Quick Start #

Initialize and automatically store the session ID. Instead of manually copying the session ID, you can store it in a shell variable:

SID=$(curl -sS -D - -o /dev/null \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0.0.1"}}}' \
  https://design-system-mcp.afp.dev.atlas.adessofinancialplatform.com/mcp \
  | awk -F': ' 'tolower($1)=="mcp-session-id" {print $2}' \
  | tr -d '\r')

echo "Session initialized: $SID"

The session ID is returned as an HTTP header: mcp-session-id: <uuid>. The response body may be returned as text/event-stream (SSE), which is expected behaviour.


Confirm Initialization #

After initialization, the client should send a notifications/initialized notification to confirm that it is ready to receive tool calls:

curl -i https://design-system-mcp.afp.dev.atlas.adessofinancialplatform.com/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H "mcp-session-id: $SID" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

List Available Tools #

To see the list of available tools, send a tools/list request:

curl -i https://design-system-mcp.afp.dev.atlas.adessofinancialplatform.com/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H "mcp-session-id: $SID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

Call Tools #

To call a tool, send a tools/call request with the appropriate parameters. For example, to list all tags in the design system:

curl -i https://design-system-mcp.afp.dev.atlas.adessofinancialplatform.com/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H "mcp-session-id: $SID" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_tags","arguments":{}}}'

Important Notes #

MCP
Share
Create a link with a predefined theme that is automatically applied when the generated link is opened. Default LBBW Presentation Mode
Abort Copy Link