GeneralBots/botbook
2
2
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add USE MCP documentation and update Sources docs

Browse source 
- New keyword-use-mcp.md: Complete docs for USE MCP keyword and mcp.csv
- Updated sources.md: MCP Servers section with mcp.csv configuration
- CSV format examples and connection type documentation
- Authentication configuration (api_key, bearer)
- Integration with Tasks and BASIC examples
This commit is contained in:
Rodrigo Rodriguez (Pragmatismo) 2025-12-13 00:27:17 -03:00
parent 89eef18cf6
commit 25355f7066
2 changed files with 702 additions and 289 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

646
src/04-gbui/apps/sources.md
View file

@ -1,182 +1,376 @@
# Sources - Prompts & Templates # Sources
> **Your bot configuration hub** > **Repositories, Apps, Prompts, Templates & MCP Servers**
<img src="../../assets/suite/sources-screen.svg" alt="Sources Interface Screen" style="max-width: 100%; height: auto;">
--- ---
<img src="../../assets/chapter-04/sources-interface.svg" alt="Sources Interface" style="max-width: 100%; height: auto;">
## Overview ## Overview
Sources is the configuration center in General Bots Suite. Manage your bots, prompts, templates, and knowledge bases all in one place. Sources is where you create new bots, customize their behavior, and organize the content that powers your AI assistant. Sources is where you connect everything your bot can reference. Add Git repositories, manage generated apps, configure prompts, and connect MCP servers. Most importantly, Sources enables **@mentions** in chat—reference `@botserver` to work on a repository or `@myapp` to modify an app you created.
--- ---
## Features ## Tabs
### Managing Bots | Tab | What It Contains |
|-----|------------------|
| **Repositories** | Git repos (GitHub, GitLab, Bitbucket) |
| **Apps** | HTMX apps created with CREATE SITE |
| **Prompts** | System prompts and templates |
| **Templates** | Bot packages (.gbai) |
| **News** | Platform updates and announcements |
| **MCP Servers** | Model Context Protocol servers |
| **LLM Tools** | Available LLM-invokable tools |
| **Models** | Configured AI models |
#### Creating a New Bot ---
1. Click **+ New Bot** in the top right ## Repositories
2. Fill in the bot details:
Connect Git repositories so Tasks can read, modify, and commit code.
### Adding a Repository
1. Click **+ Add Repository**
2. Enter the repository URL (HTTPS or SSH)
3. Authenticate if private
4. Click **Connect**
### Repository Card
Each connected repository shows:
| Field | Description | | Field | Description |
|-------|-------------| |-------|-------------|
| **Bot ID** | Unique identifier (lowercase, numbers, hyphens only) | | **Name** | Repository name with @mention tag |
| **Display Name** | User-friendly name shown in chat | | **Owner** | Organization or user |
| **Description** | Brief explanation of what the bot does | | **Description** | From repository README |
| **Start from** | Blank, Template, or Clone existing | | **Language** | Primary programming language |
| **Stars/Forks** | GitHub metrics |
| **Status** | Connected or disconnected |
#### Bot Settings ### Using @mentions with Repositories
Click the **⚙️** icon on any bot to configure: In chat, type `@` followed by the repo name:
**General Settings:** ```
You: @botserver add error handling to the login function
| Setting | Description | Bot: I'll modify botserver. Looking at the login function...
|---------|-------------| [Task created: Add error handling to login]
| **Display Name** | Name shown to users |
| **Welcome Message** | First message when conversation starts |
| **Language** | Primary language for the bot |
| **Timezone** | Bot's timezone for date/time operations |
| **Status** | Live, Draft, or Maintenance |
**Status Options:**
- **Live** - Bot is active and responding
- **Draft** - Bot is hidden from users
- **Maintenance** - Shows maintenance message
#### AI Settings
| Setting | Description |
|---------|-------------|
| **Provider** | AI provider (OpenAI, Azure, etc.) |
| **Model** | Model to use (GPT-5, Claude Sonnet 4.5, local GGUF, etc.) |
| **Temperature** | Creativity level (0 = focused, 1 = creative) |
| **Max Tokens** | Maximum response length |
| **System Prompt** | Bot personality and instructions |
| **Knowledge Base** | Connected .gbkb for answers |
---
### Managing Prompts
Prompts are reusable text templates for AI interactions.
**Prompt Types:**
| Type | Purpose |
|------|---------|
| **System Prompt** | Bot personality/behavior |
| **Task Prompt** | Specific task instructions |
| **Template** | Reusable text with variables |
**Creating a Prompt:**
1. Click **+ New Prompt**
2. Enter a name (e.g., "support-agent")
3. Select type
4. Write prompt content with optional `{{variables}}`
5. Save and link to bots
**Example Prompt:**
```botserver/docs/src/chapter-04-gbui/apps/sources-prompt-example.txt
You are a friendly and professional customer support agent
for {{company_name}}.
## Your Personality
- Be warm and empathetic
- Use simple, clear language
- Be patient and thorough
## Guidelines
- Always verify customer identity before sharing account info
- If unsure, search the knowledge base
- Escalate complex issues to human agents
- Never make promises about refunds or compensation
``` ```
--- The system will:
1. Clone or pull the latest code
2. Analyze the relevant files
3. Make the requested changes
4. Create a commit or pull request
### Managing Templates ### Repository Actions
Templates are pre-built bot packages you can reuse. | Action | Description |
|--------|-------------|
**Installed Templates:** | **Browse** | View files and folders |
| **Mention** | Insert @repo into chat |
| Template | Description | | **Disconnect** | Remove from Sources |
|----------|-------------| | **Settings** | Configure branch, credentials |
| **📋 CRM** | Full CRM with leads, contacts |
| **📋 Support** | Ticket management and customer service |
| **📋 FAQ** | Answer common questions from KB |
**Available Templates:**
| Template | Description |
|----------|-------------|
| **📋 HR** | Employee self-service |
| **📋 Analytics** | Dashboard and metrics |
| **📋 Compliance** | LGPD, GDPR compliance |
**Template Contents:**
Templates include:
- Dialog scripts (.bas files)
- Bot configuration
- Knowledge base documentation
- Sample conversations
--- ---
### Managing Knowledge Bases ## Apps
Knowledge bases store documents that your bot can search for answers. Apps are HTMX applications created with `CREATE SITE`. They appear here automatically.
### App Card
Each app shows:
| Field | Description | | Field | Description |
|-------|-------------| |-------|-------------|
| **Documents** | Count of uploaded files | | **Name** | App name with @mention tag |
| **Size** | Total storage used | | **Type** | HTMX, Dashboard, Site |
| **Last Indexed** | When content was last processed | | **Description** | Generated from creation prompt |
| **Used By** | Bots connected to this KB | | **URL** | Live endpoint (e.g., `/crm`) |
| **Created** | When the app was generated |
**Uploading Documents:** ### Using @mentions with Apps
1. Open the knowledge base Reference apps to modify them:
2. Click **Upload** or drag files
3. Organize into folders
4. Click **Reindex** to process new content
**Supported Formats:** ```
- PDF, DOCX, TXT, MD You: @crm change the submit button to green
- CSV, XLSX
- HTML, JSON Bot: I'll update the CRM app. Modifying the button styles...
[Task created: Change submit button color]
```
```
You: @dashboard add a new KPI card for monthly revenue
Bot: I'll add that to your dashboard. Creating the KPI card...
[Task created: Add monthly revenue KPI]
```
### App Actions
| Action | Description |
|--------|-------------|
| **Open** | View app in new tab |
| **Edit** | Open Tasks with app context |
| **Mention** | Insert @app into chat |
| **Delete** | Remove app and files |
--- ---
## Import and Export ## @Mention Autocomplete
### Exporting a Bot When typing in chat, `@` triggers autocomplete:
1. Click **⚙️** on the bot 1. Type `@` to see suggestions
2. Select **Export** 2. Continue typing to filter (e.g., `@bot` shows `@botserver`, `@botui`)
3. Choose what to include: 3. Press **Enter** or **Tab** to select
- Bot configuration 4. Press **Escape** to cancel
- Dialog scripts (.bas files)
- Prompts
- Knowledge base (optional, large)
- Conversation history (optional)
4. Select format: .gbai, ZIP, or JSON
### Importing a Bot ### Mention Types
1. Click **Import** at the top | Type | Icon | Example |
2. Drop file or browse (supported: .gbai, .zip) |------|------|---------|
3. Choose: | Repository | Git icon | `@botserver` |
- Create new bot, or | App | Grid icon | `@mycrm` |
- Replace existing bot
4. Configure merge options for prompts and KB ### Context for Tasks
When you mention a source, it becomes context for the task:
```
You: @botserver @botui make the API response format consistent
Bot: I'll update both repositories to use consistent response formats.
[Task created with context: botserver, botui]
```
Without explicit mentions, Tasks uses recent context or asks for clarification.
---
## Prompts
System prompts define bot personality and behavior.
### Prompt Categories
| Category | Purpose |
|----------|---------|
| **Assistants** | Role-specific personas |
| **Tools** | Tool descriptions for LLM |
| **Personas** | Bot personality definitions |
| **Custom** | Your own prompts |
### Creating a Prompt
1. Click **+ New Prompt**
2. Enter name and category
3. Write prompt content
4. Use `{{variables}}` for dynamic values
5. Click **Save**
### Prompt Actions
| Action | Description |
|--------|-------------|
| **Use** | Apply to current session |
| **Copy** | Copy to clipboard |
| **Save** | Add to collection |
| **Edit** | Modify content |
---
## Templates
Bot packages ready to deploy.
### Available Templates
| Template | Description |
|----------|-------------|
| **CRM** | Customer relationship management |
| **Support** | Helpdesk and ticketing |
| **Analytics** | Dashboards and reports |
| **Compliance** | LGPD, GDPR, HIPAA |
### Installing a Template
1. Click on template card
2. Review contents
3. Click **Install**
4. Configure settings
5. Bot is ready
---
## MCP Servers
Model Context Protocol servers extend bot capabilities. MCP servers are configured via `mcp.csv` in the bot's `.gbai` folder, making their tools available to Tasks just like BASIC keywords.
### The mcp.csv File
MCP servers are configured by adding entries to `mcp.csv` in your bot's `.gbai` folder:
```
mybot.gbai/
├── mybot.gbdialog/ # BASIC scripts
├── mybot.gbdrive/ # Files and documents
├── config.csv # Bot configuration
├── attendant.csv # Attendant configuration
└── mcp.csv # MCP server definitions
```
When botserver starts, it reads the `mcp.csv` file and loads all server configurations.
### Server Card
| Field | Description |
|-------|-------------|
| **Name** | Server identifier (used for `USE MCP` calls) |
| **Type** | filesystem, github, database, slack, etc. |
| **Status** | Active, Inactive, Error |
| **Tools** | Available tools count |
| **Source** | "directory" (from .gbmcp) |
### mcp.csv Format
The CSV file has the following columns:
| Column | Required | Description |
|--------|----------|-------------|
| `name` | Yes | Unique server identifier |
| `type` | Yes | Connection type: `stdio`, `http`, `websocket`, `tcp` |
| `command` | Yes | For stdio: command. For http/ws: URL |
| `args` | No | Command arguments (space-separated) |
| `description` | No | Human-readable description |
| `enabled` | No | `true` or `false` (default: `true`) |
| `auth_type` | No | `none`, `api_key`, `bearer` |
| `auth_env` | No | Environment variable for auth |
### Example mcp.csv
```csv
name,type,command,args,description,enabled
# MCP Server Configuration - lines starting with # are comments
filesystem,stdio,npx,"-y @modelcontextprotocol/server-filesystem /data",Access local files,true
github,stdio,npx,"-y @modelcontextprotocol/server-github",GitHub API,true,bearer,GITHUB_TOKEN
postgres,stdio,npx,"-y @modelcontextprotocol/server-postgres",Database queries,false
slack,stdio,npx,"-y @modelcontextprotocol/server-slack",Slack messaging,true,bearer,SLACK_BOT_TOKEN
myapi,http,https://api.example.com/mcp,,Custom API,true,api_key,MY_API_KEY
```
### Adding an MCP Server
**Method 1: Via UI**
1. Click **+ Add Server**
2. Enter server details
3. Configure connection type (stdio, http, websocket)
4. Test connection
5. Click **Save**
**Method 2: Via mcp.csv**
1. Open `mcp.csv` in your `.gbai` folder
2. Add a new line with server configuration
3. Restart bot or click **🔄 Reload** in Sources UI
4. Server appears automatically
### Using MCP Tools in BASIC
```bas
' Read a file using filesystem MCP server
content = USE MCP "filesystem", "read_file", {"path": "/data/config.json"}
' Query database
results = USE MCP "postgres", "query", {"sql": "SELECT * FROM users"}
' Send Slack message
USE MCP "slack", "send_message", {"channel": "#general", "text": "Hello!"}
```
### Connection Types
| Type | Description |
|------|-------------|
| **stdio** | Local process (npx, node, python) |
| **http** | REST API endpoint |
| **websocket** | WebSocket connection |
| **tcp** | Raw TCP socket |
### Popular MCP Servers
| Server | Package | Description |
|--------|---------|-------------|
| Filesystem | `@modelcontextprotocol/server-filesystem` | File operations |
| GitHub | `@modelcontextprotocol/server-github` | GitHub API |
| PostgreSQL | `@modelcontextprotocol/server-postgres` | Database queries |
| Slack | `@modelcontextprotocol/server-slack` | Messaging |
See [USE MCP](../../06-gbdialog/keyword-use-mcp.md) for complete documentation.
---
## LLM Tools
Tools that the LLM can invoke during conversations.
### Tool Sources
| Source | Description |
|--------|-------------|
| **Built-in** | Core BASIC keywords |
| **MCP** | From connected MCP servers |
| **Custom** | Your .bas files with DESCRIPTION |
### Tool Card
| Field | Description |
|-------|-------------|
| **Name** | Tool identifier |
| **Description** | What it does |
| **Parameters** | Required inputs |
| **Source** | Where it comes from |
---
## Models
Configured AI models for the platform.
### Model Card
| Field | Description |
|-------|-------------|
| **Name** | Model identifier |
| **Provider** | OpenAI, Anthropic, Local, etc. |
| **Status** | Active, coming soon |
| **Tags** | Capabilities (chat, code, vision) |
### Supported Providers
| Provider | Models |
|----------|--------|
| **OpenAI** | GPT-4, GPT-4o |
| **Anthropic** | Claude Sonnet 4.5, Claude Opus 4 |
| **Local** | llama.cpp GGUF models |
| **Azure** | Azure OpenAI deployments |
---
## Search
Use the search box to find across all source types:
- Type to search by name
- Results update as you type
- Press **Enter** to search
- Press **Escape** to clear
--- ---
@ -184,165 +378,40 @@ Knowledge bases store documents that your bot can search for answers.
| Shortcut | Action | | Shortcut | Action |
|----------|--------| |----------|--------|
| `Ctrl+N` | New bot | | `Ctrl+K` | Focus search |
| `Ctrl+S` | Save changes | | `1-6` | Switch tabs |
| `Ctrl+E` | Export selected | | `Escape` | Close modal |
| `Ctrl+I` | Import |
| `Delete` | Delete selected |
| `Ctrl+D` | Duplicate |
| `F2` | Rename |
| `/` | Search |
| `Enter` | Open selected | | `Enter` | Open selected |
| `Escape` | Close dialog |
---
## Tips & Tricks
### Bot Management
💡 **Use descriptive names** - "customer-support-v2" is better than "bot1"
💡 **Keep prompts separate** - Reuse prompts across multiple bots
💡 **Version your exports** - Export before major changes
💡 **Test in Draft mode** - Don't go Live until fully tested
### Prompt Writing
💡 **Be specific** - Clear instructions give better results
💡 **Use examples** - Show the AI what good responses look like
💡 **Set boundaries** - Define what the bot should NOT do
💡 **Use variables** - Make prompts reusable with {{placeholders}}
### Knowledge Base
💡 **Organize in folders** - Group related documents together
💡 **Keep documents current** - Remove outdated information
💡 **Use clear filenames** - "refund-policy-2025.pdf" not "doc1.pdf"
💡 **Reindex after changes** - New content isn't searchable until indexed
---
## Troubleshooting
### Bot not responding
**Possible causes:**
1. Bot is in Draft mode
2. AI provider not configured
3. No dialogs or prompts set up
**Solution:**
1. Check bot status is "Live"
2. Verify AI settings have valid API key
3. Ensure at least start.bas exists
4. Check error logs in Analytics
---
### Knowledge base not finding answers
**Possible causes:**
1. Documents not indexed
2. Document format not supported
3. Query doesn't match content
**Solution:**
1. Click "Reindex" and wait for completion
2. Convert documents to supported formats
3. Check document actually contains the information
4. Try different phrasing
---
### Import fails
**Possible causes:**
1. File corrupted
2. Incompatible version
3. Duplicate bot ID
**Solution:**
1. Try re-exporting from source
2. Check General Bots version compatibility
3. Choose "Create new bot" instead of replace
4. Rename bot ID if duplicate
---
### Prompts not applying
**Possible causes:**
1. Prompt not linked to bot
2. Variable not defined
3. Syntax error in prompt
**Solution:**
1. Check AI Settings → System Prompt selection
2. Verify all {{variables}} have values
3. Test prompt with "Test" button
4. Check for unclosed brackets or quotes
--- ---
## BASIC Integration ## BASIC Integration
Access Sources data from dialogs: ### List Repositories
### Get Bot Configuration ```bas
repos = GET REPOSITORIES
```botserver/docs/src/chapter-04-gbui/apps/sources-config.basic FOR EACH repo IN repos
config = GET BOT CONFIG TALK repo.name + " - " + repo.description
TALK "Bot name: " + config.displayName NEXT
TALK "Language: " + config.language
``` ```
### Use Prompts ### List Apps
```botserver/docs/src/chapter-04-gbui/apps/sources-prompts.basic ```bas
' Load a prompt template apps = GET APPS
prompt = GET PROMPT "summarize" FOR EACH app IN apps
TALK app.name + " at /" + app.url
' Use with variables NEXT
summary = GENERATE WITH PROMPT prompt, content
TALK summary
``` ```
### Search Knowledge Base ### Get Task Context
```botserver/docs/src/chapter-04-gbui/apps/sources-search.basic ```bas
HEAR question AS TEXT "What would you like to know?" ' Get sources mentioned in current conversation
context = GET TASK CONTEXT
results = SEARCH KB question IN "support.gbkb" FOR EACH source IN context
TALK "Working with: @" + source.name
IF COUNT(results) > 0 THEN
TALK results[0].answer
TALK "Source: " + results[0].source
ELSE
TALK "I couldn't find information about that."
END IF
```
### List Available Bots
```botserver/docs/src/chapter-04-gbui/apps/sources-list.basic
bots = GET BOTS
TALK "Available bots:"
FOR EACH bot IN bots
IF bot.status = "live" THEN
TALK "● " + bot.displayName
ELSE
TALK "○ " + bot.displayName + " (draft)"
END IF
NEXT NEXT
``` ```
@ -350,7 +419,6 @@ NEXT
## See Also ## See Also
- [Designer App](./designer.md) - Visual flow builder - [Tasks](./tasks.md) - Execute work on repositories and apps
- [Drive App](./drive.md) - Upload KB documents - [Chat](./chat.md) - Use @mentions in conversation
- [How To: Create Your First Bot](../how-to/create-first-bot.md) - [Autonomous Task AI](../../07-gbapp/autonomous-tasks.md) - How context flows to tasks
- [How To: Add Documents to Knowledge Base](../how-to/add-kb-documents.md)

345
src/06-gbdialog/keyword-use-mcp.md Normal file
View file

@ -0,0 +1,345 @@
# USE MCP
> **Invoke MCP Server Tools from BASIC**
---
## Overview
The `USE MCP` keyword allows you to invoke tools from Model Context Protocol (MCP) servers directly in your BASIC scripts. MCP servers extend your bot's capabilities by providing access to external systems like databases, filesystems, APIs, and more.
---
## Syntax
```bas
result = USE MCP "server_name", "tool_name", {parameters}
```
| Parameter | Description |
|-----------|-------------|
| `server_name` | Name of the MCP server (as defined in `mcp.csv`) |
| `tool_name` | Name of the tool to invoke |
| `parameters` | JSON object with tool parameters |
---
## The mcp.csv File
MCP servers are configured by adding entries to the `mcp.csv` file in your bot's `.gbai` folder:
```
mybot.gbai/
├── mybot.gbdialog/ # BASIC scripts
├── mybot.gbdrive/ # Files and documents
├── config.csv # Bot configuration
├── attendant.csv # Attendant configuration
└── mcp.csv # MCP server definitions
```
When botserver starts, it reads the `mcp.csv` file and loads all server configurations. These servers become available to Tasks and can be invoked using the `USE MCP` keyword.
---
## mcp.csv Format
The CSV file has the following columns:
| Column | Required | Description |
|--------|----------|-------------|
| `name` | Yes | Unique server identifier (used in `USE MCP` calls) |
| `type` | Yes | Connection type: `stdio`, `http`, `websocket`, `tcp` |
| `command` | Yes | For stdio: command to run. For http/ws: URL |
| `args` | No | Command arguments (space-separated) or empty |
| `description` | No | Human-readable description |
| `enabled` | No | `true` or `false` (default: `true`) |
| `auth_type` | No | Authentication type: `none`, `api_key`, `bearer` |
| `auth_env` | No | Environment variable name for auth credential |
| `risk_level` | No | `safe`, `low`, `medium`, `high`, `critical` |
| `requires_approval` | No | `true` or `false` (default: `false`) |
### Example mcp.csv
```csv
name,type,command,args,description,enabled
# MCP Server Configuration
# Lines starting with # are comments
filesystem,stdio,npx,"-y @modelcontextprotocol/server-filesystem /data",Access local files,true
github,stdio,npx,"-y @modelcontextprotocol/server-github",GitHub API,true,bearer,GITHUB_TOKEN
postgres,stdio,npx,"-y @modelcontextprotocol/server-postgres",Database queries,false
slack,stdio,npx,"-y @modelcontextprotocol/server-slack",Slack messaging,true,bearer,SLACK_BOT_TOKEN
myapi,http,https://api.example.com/mcp,,Custom API,true,api_key,MY_API_KEY
```
---
## Connection Types
### stdio (Local Process)
For MCP servers that run as local processes via npx, node, python, etc:
```csv
filesystem,stdio,npx,"-y @modelcontextprotocol/server-filesystem /data",File access,true
```
The `command` is the executable, and `args` contains the arguments.
### http (REST API)
For HTTP-based MCP servers:
```csv
myapi,http,https://api.example.com/mcp,,REST API server,true
```
The `command` is the URL endpoint.
### websocket
For WebSocket connections:
```csv
realtime,websocket,wss://ws.example.com/mcp,,Real-time server,true
```
### tcp
For raw TCP connections:
```csv
legacy,tcp,localhost:9000,,Legacy TCP server,true
```
Format: `host:port` in the command column.
---
## Authentication
### API Key
```csv
myapi,http,https://api.example.com,,API Server,true,api_key,MY_API_KEY
```
The environment variable `MY_API_KEY` will be read and sent as `X-API-Key` header.
### Bearer Token
```csv
github,stdio,npx,"-y @modelcontextprotocol/server-github",GitHub,true,bearer,GITHUB_TOKEN
```
The environment variable `GITHUB_TOKEN` will be used as a Bearer token.
> **Security**: Authentication credentials are read from environment variables. Never put actual secrets in mcp.csv.
---
## Examples
### Read a File
```bas
' Read a file using filesystem MCP server
content = USE MCP "filesystem", "read_file", {"path": "/data/config.json"}
TALK "File contents: " + content
```
### Query Database
```bas
' Query PostgreSQL using database MCP server
results = USE MCP "postgres", "query", {"sql": "SELECT * FROM users LIMIT 10"}
FOR EACH row IN results
TALK row.name + " - " + row.email
NEXT
```
### Search GitHub
```bas
' Search GitHub repositories
repos = USE MCP "github", "search_repositories", {"query": "general bots language:rust"}
TALK "Found " + repos.length + " repositories"
```
### Send Slack Message
```bas
' Send message to Slack channel
USE MCP "slack", "send_message", {
"channel": "#general",
"text": "Hello from General Bots!"
}
```
### Create GitHub Issue
```bas
' Create an issue (requires approval if configured)
issue = USE MCP "github", "create_issue", {
"owner": "myorg",
"repo": "myproject",
"title": "Bug: Login not working",
"body": "Users cannot log in with SSO"
}
TALK "Created issue #" + issue.number
```
---
## Related Keywords
### MCP LIST TOOLS
List available tools from an MCP server:
```bas
tools = MCP LIST TOOLS "filesystem"
FOR EACH tool IN tools
TALK tool.name + ": " + tool.description
NEXT
```
### MCP INVOKE
Alternative syntax for direct tool invocation:
```bas
result = MCP INVOKE "filesystem.read_file", {"path": "/data/file.txt"}
```
---
## Risk Levels
Tools have risk levels that determine how they're handled:
| Level | Description | Behavior |
|-------|-------------|----------|
| **safe** | Read-only, no side effects | Always allowed |
| **low** | Minor changes, reversible | Usually allowed |
| **medium** | Significant changes | May require approval |
| **high** | Destructive or irreversible | Requires approval |
| **critical** | System-level changes | Always requires approval |
When `requires_approval` is set to `true`, the task will pause and wait for human approval before executing the tool.
---
## Tool Discovery
MCP tools are discovered automatically when the server starts. You can see available tools in:
1. **Sources UI** → MCP Servers tab → View Tools
2. **Sources UI** → LLM Tools tab → MCP Tools section
3. **BASIC** → `MCP LIST TOOLS "server_name"`
---
## Available MCP Servers
Popular MCP servers you can use:
| Server | Package | Description |
|--------|---------|-------------|
| **Filesystem** | `@modelcontextprotocol/server-filesystem` | File operations |
| **GitHub** | `@modelcontextprotocol/server-github` | GitHub API |
| **PostgreSQL** | `@modelcontextprotocol/server-postgres` | Database queries |
| **SQLite** | `@modelcontextprotocol/server-sqlite` | SQLite database |
| **Slack** | `@modelcontextprotocol/server-slack` | Slack messaging |
| **Puppeteer** | `@modelcontextprotocol/server-puppeteer` | Browser automation |
| **Brave Search** | `@modelcontextprotocol/server-brave-search` | Web search |
See [modelcontextprotocol.io](https://modelcontextprotocol.io) for more servers.
---
## Integration with Tasks
When you add MCP servers to your bot via `mcp.csv`, their tools become available to the Autonomous Task system. The AI can:
1. **Discover tools** from your MCP servers
2. **Plan execution** using MCP tools alongside BASIC keywords
3. **Request approval** for high-risk operations
4. **Execute tools** and process results
Example task flow:
```
User: "Read the config file and update the database accordingly"
AI Plan:
1. USE MCP "filesystem", "read_file" → Read config.json
2. Parse JSON configuration
3. USE MCP "postgres", "query" → Update database
4. Report results
```
---
## Troubleshooting
### Server Not Found
```
Error: MCP server 'myserver' not found
```
- Check that `mcp.csv` exists in your `.gbai` folder
- Verify the server name matches exactly (case-sensitive)
- Ensure `enabled` is not set to `false`
- Reload servers in Sources UI
### Connection Failed
```
Error: Failed to connect to MCP server
```
- Verify the command/URL is correct
- Check that required packages are installed (`npm install`)
- Ensure environment variables are set for authentication
- Test the server manually first
### Tool Not Available
```
Error: Tool 'unknown_tool' not found on server 'myserver'
```
- List available tools with `MCP LIST TOOLS`
- Check tool name spelling
- Verify server is properly started
### Authentication Error
```
Error: Authentication failed for MCP server
```
- Check environment variables are set correctly
- Verify credentials are valid
- Ensure auth type matches server requirements
---
## Best Practices
1. **Use environment variables** for all credentials
2. **Set appropriate risk levels** for tools that modify data
3. **Enable approval** for destructive operations
4. **Comment your mcp.csv** with `#` lines to document servers
5. **Test locally** before deploying
6. **Start with enabled=false** for new servers until tested
---
## See Also
- [Sources](../04-gbui/apps/sources.md) - Managing MCP servers in the UI
- [Autonomous Tasks](../07-gbapp/autonomous-tasks.md) - How Tasks use MCP tools
- [MCP Format](../09-tools/mcp-format.md) - MCP tool definition format
- [LLM Tools](../09-tools/README.md) - All available tool types