# 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:

```ts
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:

```json
{
  "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:

```bash
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

![Three panels: in Auto the chat can use UI tools and MCP tools; in UI only UI tools; in MCP only MCP tools](/docs/diagrams/modes.svg "Execution modes")

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

| Mode | Tools that the chat can use | Use it to |
| --- | --- | --- |
| Auto (default) | UI tools and MCP tools | Let the chat choose. It uses app operations for data and the UI for visible changes. |
| UI | UI tools only | Open forms, fill fields and save through the controls of your app. |
| MCP | MCP tools only | Read or change data directly. |

- 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:

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

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