From dce8c8c2358b34a0908e4be41ff5aec7d7c5bca3 Mon Sep 17 00:00:00 2001
From: benjdlambert <ben@blam.sh>
Date: Tue, 17 Jun 2025 12:50:03 +0200
Subject: [PATCH] feat: added some documentation for mcp actions backend

Signed-off-by: benjdlambert <ben@blam.sh>
---
 .../config/vocabularies/Backstage/accept.txt  |   1 +
 plugins/mcp-actions-backend/README.md         | 124 +++++++++++++++++-
 2 files changed, 120 insertions(+), 5 deletions(-)

diff --git a/.github/vale/config/vocabularies/Backstage/accept.txt b/.github/vale/config/vocabularies/Backstage/accept.txt
index 36f9335b1f..92c7a293f5 100644
--- a/.github/vale/config/vocabularies/Backstage/accept.txt
+++ b/.github/vale/config/vocabularies/Backstage/accept.txt
@@ -433,6 +433,7 @@ statefulsets
 stdout
 storable
 storages
+Streamable
 stringified
 stringify
 subcommand
diff --git a/plugins/mcp-actions-backend/README.md b/plugins/mcp-actions-backend/README.md
index 5e1ab57904..8994bf361a 100644
--- a/plugins/mcp-actions-backend/README.md
+++ b/plugins/mcp-actions-backend/README.md
@@ -1,6 +1,6 @@
-# MCP Backend
+# MCP Actions Backend
 
-This plugin backend was templated using the Backstage CLI. You should replace this text with a description of your plugin backend.
+This plugin exposes Backstage actions as MCP (Model Context Protocol) tools, allowing AI clients to discover and invoke registered actions in your Backstage backend.
 
 ## Installation
 
@@ -19,10 +19,124 @@ const backend = createBackend();
 backend.add(import('@backstage/plugin-mcp-actions-backend'));
 ```
 
+## Configuration
+
+### Configuring Actions Registry
+
+The MCP Actions Backend exposes actions that are registered with the Actions Registry. You can register actions from specific plugins by configuring the `pluginSources` in your app configuration:
+
+```yaml
+backend:
+  actions:
+    pluginSources:
+      - 'catalog'
+      - 'my-custom-plugin'
+```
+
+Actions from these plugins will be discovered and exposed as MCP tools. Each action must be registered using the Actions Registry Service in the respective plugin:
+
+```ts
+// In your plugin
+import { actionsRegistryServiceRef } from '@backstage/backend-plugin-api/alpha';
+
+export const myPlugin = createBackendPlugin({
+  pluginId: 'my-custom-plugin',
+  register(env) {
+    env.registerInit({
+      deps: {
+        actionsRegistry: actionsRegistryServiceRef,
+      },
+      async init({ actionsRegistry }) {
+        actionsRegistry.register({
+          name: 'greet-user',
+          title: 'Greet User',
+          description: 'Generate a personalized greeting',
+          schema: {
+            input: z =>
+              z.object({
+                name: z.string().describe('The name of the person to greet'),
+              }),
+            output: z =>
+              z.object({
+                greeting: z.string().describe('The generated greeting'),
+              }),
+          },
+          action: async ({ input }) => ({
+            output: { greeting: `Hello ${input.name}!` },
+          }),
+        });
+      },
+    });
+  },
+});
+```
+
+### Authentication Configuration
+
+By default, the Backstage backend requires authentication for all requests. For MCP clients to access the actions, you have several authentication options:
+
+We're looking at [device authentication](https://github.com/backstage/backstage/pull/27680) to make this much easier with authentication for MCP clients, but currently you have the following choices:
+
+#### External Access with Static Tokens
+
+Configure external access with static tokens in your app configuration:
+
+```yaml
+backend:
+  auth:
+    externalAccess:
+      - type: static
+        options:
+          token: ${MCP_TOKEN}
+```
+
+Generate a secure token:
+
+```bash
+node -p 'require("crypto").randomBytes(24).toString("base64")'
+```
+
+Set the `MCP_TOKEN` environment variable with this token, and configure your MCP client to use it in the [Authorization header](#configuring-mcp-clients)
+
+#### Disable Default Auth Policy (Development Only)
+
+For development environments, you can disable the default authentication policy:
+
+```yaml
+backend:
+  auth:
+    dangerouslyDisableDefaultAuthPolicy: true
+```
+
+⚠️ **Warning**: This setting disables authentication requirements and should **never** be used in production environments.
+
+## Configuring MCP Clients
+
+The MCP server supports both Server-Sent Events (SSE) and Streamable HTTP protocols.
+
+The SSE protocol is deprecated, and should be avoided as it will be removed in a future release.
+
+- `Streamable HTTP`: `http://localhost:7007/api/mcp-actions/v1`
+- `SSE`: `http://localhost:7007/api/mcp-actions/v1/sse`
+
+There's a few different ways to configure MCP tools, but here's a snippet of the most common.
+
+```json
+{
+  "mcpServers": {
+    "backstage-actions": {
+      // you can also replace this with the public / internal URL of the deployed backend.
+      "url": "http://localhost:7007/api/mcp-actions/v1",
+      "headers": {
+        "Authorization": "Bearer ${MCP_TOKEN}"
+      }
+    }
+  }
+}
+```
+
 ## Development
 
-This plugin backend can be started in a standalone mode from directly in this
-package with `yarn start`. It is a limited setup that is most convenient when
-developing the plugin backend itself.
+This plugin backend can be started in a standalone mode from directly in this package with `yarn start`. It is a limited setup that is most convenient when developing the plugin backend itself.
 
 If you want to run the entire project, including the frontend, run `yarn start` from the root directory.