Chapter 6: Updating The App Definitions

ACME Banking's assistant can now see the selected client through Working Context, but it still needs better knowledge of the applications available in the platform.

MCP Web includes built-in system tools that can search for io.Connect applications and workspace layouts, then start the best match for the user's request. Those tools depend on the platform definitions. If the definitions contain only app names and URLs, the assistant has very little to reason over. It may know that an app named client-portfolio exists, but it doesn't know when to use it, what context it expects, or what interop methods it exposes.

In this chapter, you will enrich the definitions for:

• client-list
• client-portfolio
• the client-management workspace layout

With these definitions in place, the assistant can map requests such as "show me my clients" or "show me the portfolio details for Amelia Reed" to the real platform apps and workspace layout.

Related API References

The metadata in this chapter is consumed by MCP Core and MCP Web system tools:

• MCP Core Overview
• MCP Core API Reference
• MCP Core Tool Types
• MCP Web Server API

Why Definitions Matter

The assistant doesn't inspect your source code. It learns what the platform can do through tools and metadata.

For app and workspace discovery, the most important metadata is:

Metadata	Why it matters
caption	Gives the system search tools a plain-language explanation of what the app does. Apps without captions can't be explained well and may be filtered out of search results.
customProperties.interop.context	Describes the context an app reads or writes, including the source and schema. This helps the assistant understand how apps coordinate through workspace context.
customProperties.interop.methods	Describes interop methods exposed by an app. This helps the assistant know which methods can be used after an app is started.
metadata.description	Explains what a workspace layout is for. This helps the assistant decide when a saved workspace is a better match than opening one app by itself.
metadata.contextSchema	Describes the context a workspace can receive when it is started. This lets the assistant provide useful startup context to the workspace.

The goal is to make the platform self-describing. When the LLM decides how to help the advisor, it should have enough structured information to choose the right app, workspace, and context.

Open The Platform Config

Open:

io-assist-anywhere-start/apps/io-cb-home/src/config.json

The apps array already contains the two banking apps:

apps/io-cb-home/src/config.json

{
  "name": "client-list",
  "type": "window",
  "details": {
    "url": "http://localhost:4201"
  },
  "customProperties": {
    "includeInWorkspaces": true
  }
}

apps/io-cb-home/src/config.json

{
  "name": "client-portfolio",
  "type": "window",
  "details": {
    "url": "http://localhost:4202"
  },
  "customProperties": {
    "includeInWorkspaces": true
  }
}

You will keep the existing name, type, details, and includeInWorkspaces values, and add the missing descriptive metadata.

Update The Client List Definition

The Client List app displays ACME Banking clients and writes selectedClient to the workspace context when the advisor selects a client.

Update the client-list definition:

apps/io-cb-home/src/config.json

{
  "name": "client-list",
  "type": "window",
  "details": {
    "url": "http://localhost:4201"
  },
  "caption": "Displays ACME Banking clients and lets an advisor select the active client for the current workspace. On selection, writes selectedClient metadata to Workspace Context.",
  "customProperties": {
    "includeInWorkspaces": true,
    "interop": {
      "context": {
        "sources": [
          "workspace"
        ],
        "description": "Writes the selected ACME Banking client to Workspace Context so portfolio and assistant apps can use the current client selection.",
        "schema": {
          "type": "object",
          "properties": {
            "selectedClient": {
              "type": "object",
              "description": "The ACME Banking client currently selected in the workspace.",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Client identifier, for example CL-10031."
                },
                "portfolioId": {
                  "type": "string",
                  "description": "Portfolio identifier associated with the client, for example PF-8817."
                },
                "firstName": {
                  "type": "string",
                  "description": "Client first name."
                },
                "lastName": {
                  "type": "string",
                  "description": "Client last name."
                },
                "fullName": {
                  "type": "string",
                  "description": "Client full name."
                },
                "segment": {
                  "type": "string",
                  "description": "Banking segment, for example Wealth, Retail Plus, or Private Banking."
                },
                "advisor": {
                  "type": "string",
                  "description": "Advisor assigned to the client."
                },
                "riskProfile": {
                  "type": "string",
                  "description": "Client investment risk profile."
                },
                "selectedAt": {
                  "type": "string",
                  "description": "ISO timestamp for when the client was selected."
                }
              },
              "required": [
                "id",
                "portfolioId",
                "firstName",
                "lastName",
                "fullName"
              ]
            }
          },
          "required": [
            "selectedClient"
          ]
        }
      }
    }
  }
}

The caption explains the app's purpose in natural language. The context metadata explains the exact workspace context shape the app writes.

Update The Client Portfolio Definition

The Client Portfolio app reads the selected client from workspace context and displays that client's portfolio. It also exposes the ClientPortfolio.Display interop method so other apps, tools, or workflows can ask it to display a portfolio by client id.

Update the client-portfolio definition:

apps/io-cb-home/src/config.json

{
  "name": "client-portfolio",
  "type": "window",
  "details": {
    "url": "http://localhost:4202"
  },
  "caption": "Displays portfolio details for the ACME Banking client selected in Workspace Context. Shows portfolio value, cash balance, YTD return, holdings, and recent activity.",
  "customProperties": {
    "includeInWorkspaces": true,
    "interop": {
      "methods": [
        {
          "name": "ClientPortfolio.Display",
          "description": "Displays portfolio details for a client by client id or portfolio id.",
          "inputSchema": {
            "type": "object",
            "properties": {
              "clientId": {
                "type": "string",
                "description": "Client identifier to display, for example CL-10031."
              },
              "id": {
                "type": "string",
                "description": "Alternative client identifier. Use this when the caller has an id field instead of clientId."
              }
            }
          },
          "outputSchema": {
            "type": "object",
            "properties": {
              "ok": {
                "type": "boolean",
                "description": "Whether the portfolio was found and displayed."
              },
              "clientId": {
                "type": "string",
                "description": "Resolved client identifier."
              },
              "portfolioId": {
                "type": "string",
                "description": "Resolved portfolio identifier."
              },
              "fullName": {
                "type": "string",
                "description": "Resolved client full name."
              },
              "message": {
                "type": "string",
                "description": "Error or status message when the portfolio cannot be displayed."
              }
            },
            "required": [
              "ok"
            ]
          }
        }
      ],
      "context": {
        "sources": [
          "workspace"
        ],
        "description": "Reads selectedClient from Workspace Context and automatically displays that client's portfolio when the selection changes.",
        "schema": {
          "type": "object",
          "properties": {
            "selectedClient": {
              "type": "object",
              "description": "The ACME Banking client selected in the workspace.",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Client identifier used to load portfolio details."
                },
                "portfolioId": {
                  "type": "string",
                  "description": "Portfolio identifier associated with the selected client."
                },
                "fullName": {
                  "type": "string",
                  "description": "Selected client full name."
                }
              },
              "required": [
                "id"
              ]
            }
          },
          "required": [
            "selectedClient"
          ]
        }
      }
    }
  }
}

This definition gives the assistant two important pieces of knowledge:

• The app is useful when the advisor needs portfolio details.
• The app can receive or act on a client identifier through context and interop.

Update The Workspace Definition

The client-management workspace opens both banking apps together. That makes it a better match for a client-service workflow than launching either app alone.

Find the client-management layout:

apps/io-cb-home/src/config.json

{
  "name": "client-management",
  "type": "Workspace",
  "metadata": {},
  "components": []
}

Replace the empty metadata object with a description and context schema:

apps/io-cb-home/src/config.json

{
  "metadata": {
    "description": "A workspace layout for ACME Banking client management. It includes a client list for selecting the active client and a portfolio view that displays portfolio details from the selected workspace client context.",
    "contextSchema": {
      "type": "object",
      "properties": {
        "selectedClient": {
          "type": "object",
          "description": "The ACME Banking client currently selected in the workspace.",
          "properties": {
            "id": {
              "type": "string",
              "description": "Client identifier, for example CL-10031."
            },
            "portfolioId": {
              "type": "string",
              "description": "Portfolio identifier associated with the client, for example PF-8817."
            },
            "firstName": {
              "type": "string",
              "description": "Client first name."
            },
            "lastName": {
              "type": "string",
              "description": "Client last name."
            },
            "fullName": {
              "type": "string",
              "description": "Client full name."
            },
            "segment": {
              "type": "string",
              "description": "Banking segment, for example Wealth, Retail Plus, or Private Banking."
            },
            "advisor": {
              "type": "string",
              "description": "Advisor assigned to the client."
            },
            "riskProfile": {
              "type": "string",
              "description": "Client investment risk profile."
            },
            "selectedAt": {
              "type": "string",
              "description": "ISO timestamp for when the client was selected."
            }
          },
          "required": [
            "id",
            "portfolioId",
            "firstName",
            "lastName",
            "fullName"
          ]
        }
      },
      "required": [
        "selectedClient"
      ]
    }
  }
}

Keep the existing components structure as it is. You are only replacing metadata.

The description helps the search system understand when to restore this workspace. The contextSchema tells the start-workspace system tool which context values can be passed when opening the workspace.

Build The Platform

Build the platform app:

npm run build --workspace d-io-cb-home

The build should complete successfully. If it fails, check config.json for a missing comma or mismatched brace.

Run The Full Local System

Start the backend in one terminal:

cd agentic-backend
npm start

Start the frontend package in another terminal:

cd io-assist-anywhere-start
npm start

Open the platform:

http://localhost:4200

Launch either io-assist-angular or io-assist-react.

Verify App Discovery

Ask the assistant:

show me my clients

The assistant should discover the static get_clients tool that you registered through MCP Web in Chapter 2 and return the ACME Banking client list.

Then ask a follow-up:

show me the portfolio details for Amelia Reed

At this point the pieces should come together:

1. The assistant understands the client details from the get_clients result.
2. The MCP Web system search tools can discover the relevant apps and workspace layout from the enriched definitions.
3. The start-workspace system tool can open the client-management workspace with the selected client context.
4. The Client Portfolio app reads that workspace context and displays Amelia Reed's portfolio.

If the assistant returns the clients but doesn't open the right workflow, review the caption, customProperties.interop, and metadata fields. They are the bridge between the advisor's natural-language request and the actual apps available in io.Connect Browser.

ACME Banking now has an assistant that can understand the platform, discover the right applications, and start a meaningful client workflow instead of only answering text questions.