App tools (MCP)

The chat uses the operations of your app through the Model Context Protocol (MCP). Your app supplies an MCP server. The chat finds its tools and calls them. The chat does not copy your business logic or your data.

Connect an HTTP MCP server

In Shappy Backend, open Tools / MCP. Enter the MCP URL of your app and a bearer key with a limited scope.

In a browser-local runtime, add the connection in code:

const connections = new McpConnections();
await connections.add({
  id: 'my-app',
  url: 'https://app.example.com/mcp',
  headers: { Authorization: `Bearer ${scopedKey}` },
});

Use an http: or https: URL. Do not put a user name or password in the URL.

The runtime starts the MCP session and reads all tools, one page at a time. For each call, it compares the input with the tool schema. Then it calls the tool.

Connect a stdio MCP server

Shappy Backend can start an MCP server as a local process. Put the connection in a private configuration file:

{
  "connections": [
    {
      "transport": "stdio",
      "id": "my-app",
      "command": "/usr/local/bin/node",
      "args": ["dist/mcp.js"],
      "cwd": "/path/to/my-app",
      "inheritEnv": ["MY_APP_API_TOKEN", "MY_APP_URL"]
    }
  ]
}

Start the backend with this file:

SHAPPYCHAT_CONFIG=/path/to/shappychat.local.json ./app.sh start

• The command and the path come from your configuration. The model cannot change them.
• inheritEnv lists the environment variables that the process gets. Supply secrets through the environment, not in the file.
• Your app still checks the permissions of each operation.

The backend also makes these tools available over HTTP at http://127.0.0.1:8849/mcp. Clients such as the Chrome extension can use them with a credential that grants the connection.

Choose how the chat acts

The message field shows an execution mode: Auto, UI or MCP.

• Click the mode to open the menu. Or press Shift + Tab in the message field.
• The chat saves the mode for each conversation.
• If you change the mode during a reply, the new mode applies to the next reply.
• If the tools of a mode are not available, UI or MCP mode shows an error before the model starts.

You can also set the mode in code:

await runtime.configure({ executionMode: 'ui' });
const { executionMode, activeExecutionMode } = runtime.getSnapshot();

Note: The execution mode selects the tools. It is not a security sandbox.