# Vertex Mcp Chatbot

> Vertex AI chatbot with MCP integration

- **Type:** MCP server
- **Install:** `agentstack add mcp-intertwine-vertex-mcp-chatbot`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [intertwine](https://agentstack.voostack.com/s/intertwine)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [intertwine](https://github.com/intertwine)
- **Source:** https://github.com/intertwine/vertex-mcp-chatbot

## Install

```sh
agentstack add mcp-intertwine-vertex-mcp-chatbot
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Vertex MCP Chatbot

[](https://www.python.org)
[](https://modelcontextprotocol.io)
[](https://github.com/modelcontextprotocol/python-sdk)
[](https://spec.modelcontextprotocol.io/specification/)
[](https://modelcontextprotocol.io)
[](https://opensource.org/licenses/MIT)

An interactive command-line chatbot for Google Cloud Vertex AI, supporting both **Anthropic's Claude** and **Google Gemini** models. Choose your preferred AI provider with a simple flag. The chatbot features full MCP (Model Context Protocol) integration with Claude, allowing autonomous tool discovery and execution during conversations. Supports Vertex AI or direct Anthropic API access, with automatic tool calling, multi-turn conversations, and comprehensive error handling.

## Features

- 🤖 **Interactive Chat Interface**: Clean, intuitive terminal UI with rich formatting
- 🔀 **Multi-Provider Support**: Choose between Claude (default) or Gemini with `--provider` flag
- 🧠 **Claude via Vertex AI**: Anthropic's Claude Sonnet 4.5 through Google Cloud Vertex AI
- 🌟 **Gemini Integration**: Google's Gemini 2.5 Flash available as alternative provider
- 🔧 **Automatic Tool Calling** (Claude): Autonomous MCP tool discovery and execution during conversations
- 📝 **Markdown Support**: Responses are rendered with proper markdown formatting
- 💾 **Persistent History**: Conversation history saved between sessions on disk
- 🎨 **Rich Terminal UI**: Colorful, well-formatted output using Rich library
- 🔧 **Flexible Configuration**: Use Vertex AI (with GCP credentials) or direct Anthropic API
- 🔌 **Full MCP Integration**: Load tools from `mcp_config.json` with automatic tool discovery and execution

### MCP Features

The chatbot includes comprehensive MCP (Model Context Protocol) support:

- ✅ **Tool Execution**: Claude automatically uses MCP tools during conversations
- ✅ **Resource Access**: Read files, APIs, and other resources via URIs
- ✅ **Prompt Templates**: Use pre-defined templates for common tasks
- ✅ **Multiple Transports**: stdio, HTTP, and SSE protocols supported
- ✅ **Multi-Server Support**: Connect to multiple MCP servers simultaneously
- ✅ **Authentication**: OAuth 2.0, Basic Auth, and custom headers
- ✅ **Reliability**: Automatic retry with exponential backoff
- ✅ **Priority System**: Smart conflict resolution when servers offer similar tools

## Quick Start

```bash
# 1. Clone and setup
git clone https://github.com/intertwine/vertex-mcp-chatbot.git
cd vertex-mcp-chatbot
make setup            # Install dependencies and create .env

# 2. Configure (edit .env file with your GCP project settings)
nano .env             # or use your preferred editor

# 3. Authenticate and run
make auth             # Authenticate with Google Cloud
make run              # Start the chatbot with quiet MCP logging!
```

For all available commands, run:

```bash
make help
```

## Prerequisites

- Python 3.10 or higher
- [uv](https://docs.astral.sh/uv/) package manager installed
- Access to Google Cloud Vertex AI with Anthropic Claude enabled (MCP-capable regions)
- Google Cloud CLI (`gcloud`) installed and authenticated

## Installation

1. Clone this repository:

```bash
git clone https://github.com/intertwine/vertex-mcp-chatbot.git
cd vertex-mcp-chatbot
```

1. Run the quick setup (installs dependencies and creates .env file):

```bash
make setup
```

> This runs `uv sync` and copies `.env.example` to `.env`

1. Edit `.env` to override default project settings:

```bash
GOOGLE_CLOUD_PROJECT='your-gcp-project-id'
GOOGLE_CLOUD_LOCATION='us-east1'
```

1. Authenticate with Google Cloud:

```bash
make auth
```

> This runs `gcloud auth application-default login`

**Alternative manual setup:**

```bash
# Install dependencies manually
uv sync

# Copy environment file
cp .env.example .env

# Authenticate manually
gcloud auth application-default login
```

## Usage

### Basic Usage

Start the chatbot with the default provider (Claude):

```bash
make run
```

### Choosing Your AI Provider

**Use Claude (default)**:

```bash
make run              # Uses Claude Sonnet 4.5 (quiet MCP logging)
make run-claude       # Same as above (quiet MCP logging)
make run-opus         # Uses Claude Opus 4.1 (quiet MCP logging)
make run-haiku        # Uses Claude Haiku 4.5 (quiet MCP logging)
```

**Use Gemini**:

```bash
make run-gemini       # Uses Gemini 2.5 Flash (quiet MCP logging)
make run-gemini-pro   # Uses Gemini 2.5 Pro (quiet MCP logging)
```

**With verbose logging**:

```bash
make run-verbose      # Claude with INFO-level MCP logging
make run-debug        # Claude with DEBUG-level MCP logging
```

**Alternative (direct uv commands)**:

```bash
uv run main.py                    # Claude Sonnet 4.5 (default)
uv run main.py --model claude-opus-4-1-20250805  # Claude Opus
uv run main.py --model claude-haiku-4-5           # Claude Haiku 4.5
uv run main.py --provider gemini  # Gemini 2.5 Flash
uv run main.py --provider gemini --model gemini-2.5-pro  # Gemini 2.5 Pro

# Logging control options
uv run main.py --quiet-mcp        # Suppress MCP server info logging
uv run main.py --log-level DEBUG  # Show detailed MCP debug information
uv run main.py --log-level ERROR  # Only show errors from MCP operations
```

**Key Differences**:

- **Claude**: Full MCP tool-calling support with autonomous tool discovery and execution
- **Gemini**: Fast, efficient responses; MCP servers can be configured but tool calling is manual

Both providers offer the same intuitive terminal interface, markdown rendering, and persistent conversation history.

### Configuring Claude via Vertex AI

The CLI automatically attempts to run Claude through Google Cloud Vertex AI using Application Default Credentials. To customise the behaviour, set any of the following environment variables before launching the REPL (they can be stored in `.env`):

- `CLAUDE_VERTEX_ENABLED` – set to `false` to fall back to the public Anthropic API (requires `ANTHROPIC_API_KEY`)
- `CLAUDE_VERTEX_PROJECT` – override the GCP project used for billing (`GOOGLE_CLOUD_PROJECT` is used otherwise)
- `CLAUDE_VERTEX_LOCATION` – override the Vertex region (defaults to `GOOGLE_CLOUD_LOCATION` or `us-east1`)
- `CLAUDE_VERTEX_BASE_URL` – fully override the Vertex endpoint if you need to point at a proxy
- `CLAUDE_MODEL` – override the default Claude model (default: `claude-sonnet-4-5-20250929`)
- `CLAUDE_API_VERSION` – override the Anthropic API version header (default: `2023-06-01`)

See [docs/claude-agent.md](docs/claude-agent.md) for an end-to-end walkthrough that covers authentication, MCP configuration, and troubleshooting tips when connecting Claude through Vertex AI, plus guidance on when to prefer the legacy Gemini provider.

### MCP Configuration

To use MCP features, create an `mcp_config.json` file in the project root. See the [MCP User Guide](docs/mcp-guide.md) for detailed configuration instructions and examples.

#### Example: Autonomous Tool Usage

When you connect to an MCP server, Claude automatically sees available tools and can use them during conversations:

```text
You > /mcp connect filesystem
✅ Connected to MCP server: filesystem

You > Please list the files in the current directory

Claude: The current directory contains the following files:
  1. CODE_OF_CONDUCT.md (1.3 KB)
  2. pyproject.toml (1.9 KB) - Python project configuration
  3. README.md (24.6 KB) - Project documentation
  4. main.py (1.7 KB) - Main Python script
  ...
```

Claude automatically:

- Discovered the `list_files` tool from the connected MCP server
- Decided to call it with appropriate parameters
- Received and processed the results
- Formatted them into a helpful response

No explicit tool invocation needed - Claude autonomously chooses when and how to use tools!

### Controlling MCP Logging

**Note**: The default `make run` targets now use `--quiet-mcp` for cleaner output. Use `make run-verbose` or `make run-debug` if you need more detailed logging.

The chatbot provides options to control the verbosity of MCP server logging:

**Suppress MCP logging (quiet mode):**

```bash
uv run main.py --quiet-mcp
```

This suppresses all informational logging from MCP operations, showing only errors.

**Adjust logging level:**

```bash
uv run main.py --log-level DEBUG    # Show detailed debug information
uv run main.py --log-level INFO     # Show informational messages
uv run main.py --log-level WARNING  # Default - show warnings and above
uv run main.py --log-level ERROR    # Show only errors
uv run main.py --log-level CRITICAL # Show only critical errors
```

These options are useful when:

- You want a cleaner output during tool execution (`--quiet-mcp`)
- You're debugging MCP server connections (`--log-level DEBUG`)
- You only care about errors (`--log-level ERROR`)

### Scrollable Content

When responses or content are too long for your terminal, the chatbot automatically switches to a scrollable view:

**Navigation Controls:**

- **↑/↓** or **j/k** - Scroll up/down line by line
- **Home/g** - Jump to the top of the content
- **End/G** - Jump to the bottom of the content
- **q/Esc** - Exit scrollable view and return to chat

**Features:**

- Automatically detects when content exceeds terminal height
- Works for:
  - LLM responses
  - `/history` command
  - `/mcp tools` listings
  - `/mcp resources` listings
  - `/mcp prompts` listings
- Preserves all markdown formatting and styling
- Short content displays normally (no change in experience)

### Available Commands

While chatting, you can use these commands:

- `/help` - Show available commands and tips
- `/clear` - Clear the chat history and start fresh (resets the Claude session)
- `/history` - Display the full conversation history with markdown rendering
- `/system ` - Update the system instruction and restart the Claude agent
- `/quit` - Exit the chatbot

**MCP Commands** (when MCP is available):

- `/mcp connect ` - Connect to an MCP server from your config
- `/mcp list` - Show configured servers and their connection status
- `/mcp disconnect ` - Disconnect from an MCP server
- `/mcp tools` - Show available tools from all connected servers
- `/mcp resources` - Show available resources from all connected servers
- `/mcp prompts` - List available prompt templates from all connected servers
- `/mcp prompt ` - Use a specific prompt template

### MCP Tool Integration

When MCP servers are connected, their tools become automatically available during conversations. Claude will intelligently use these tools when appropriate to help answer your questions or perform tasks. You don't need to use special syntax - just chat naturally and Claude will:

- Recognize when a tool would be helpful
- Execute the appropriate tool with the right parameters
- Include the tool results in its response

For example, if you have a weather MCP server connected and ask "What's the weather like?", Claude will automatically use the weather tool to get current conditions.

### MCP Resource Integration

MCP resources are automatically read when you reference them by URI in your messages. This allows you to seamlessly include external data in your conversations with Claude:

- **Automatic Detection**: When you include a resource URI in your message, it's automatically detected
- **Transparent Reading**: The resource content is fetched and included in the context sent to Claude
- **Multiple Resources**: You can reference multiple resources in a single message
- **Standard URI Format**: Use standard URIs like `file:///path/to/data.json` or `http://example.com/api/data`

**Example:**

```text
You> Can you analyze the data in file:///home/user/sales_report.csv?

[The chatbot automatically reads the CSV file and includes its content in the prompt to Claude,
who can then analyze and discuss the data]
```

### MCP Prompt Templates

MCP servers can provide prompt templates that help structure interactions for specific tasks. These templates make it easy to perform complex operations with consistent formatting:

- **List Templates**: Use `/mcp prompts` to see all available templates
- **Use a Template**: Use `/mcp prompt ` to apply a template
- **Interactive Arguments**: The chatbot will prompt you for any required template arguments
- **Seamless Processing**: Filled templates are sent directly to Claude for processing

**Example:**

```text
You> /mcp prompts
Available prompts from code-analyzer:
  - analyze_function: Analyze a function for complexity and suggest improvements
  - review_pr: Review pull request changes and provide feedback
  - explain_code: Explain how a piece of code works in simple terms

You> /mcp prompt analyze_function
Enter value for 'function_name': calculateTotalPrice
Enter value for 'context': This function processes shopping cart items

[The template is filled with your values and sent to Claude, who provides
a detailed analysis of the function based on the structured prompt]
```

### Example Session

```text
🚀 Starting Claude Agent REPL...
✅ Ready!

You> What is machine learning?

╭─ Claude ─────────────────────────────────────────────╮
│                                                      │
│  Machine learning (ML) is a branch of artificial     │
│  intelligence focused on building systems that can   │
│  learn from data and improve their performance over  │
│  time without being explicitly programmed for every  │
│  scenario...                                         │
│                                                      │
╰──────────────────────────────────────────────────────╯

You> /system You are a patient tutor for high-school students.
System prompt updated.

You> Explain overfitting in one paragraph.

╭─ Claude ─────────────────────────────────────────────╮
│                                                      │
│  Overfitting happens when a model memorises the      │
│  training data instead of learning the underlying    │
│  patterns, so it performs well on the data it has    │
│  seen but poorly on new examples. A simple way to    │
│  picture it is a student who only studies past exam  │
│  answers: they may ace the practice questions yet    │
│  struggle when the real test words things slightly   │
│  differently.                                        │
│                                                      │
╰──────────────────────────────────────────────────────╯

You> /quit

👋 Goodbye!
```

## MCP Configuration (docs/mcp-guide.md)

### Basic Configuration

Create an `mcp_config.json` file in the project root:

```json
{
  "servers": [
    {
      "name": "filesystem",
      "transport": "stdio",
      "command": ["python", "examples/mcp-servers/filesystem_server.py"]
    },
    {
      "name": "weather-api",
      "transport": "http",
      "url": "http://localhost:8080/mcp",
      "auth": {
        "type": "basic",
        "username": "user",
        "password": "pass"
      }
    }
  ]
}
```

### Environment Variables

The MCP configuration supports environment variable substitution using `${VAR_NAME}` syntax. Variables are automatically loaded from your `.env` file:

```bash
# .env file
API_KEY=your-secret-key
OAUTH_CLIENT_SECRET=your-oauth-secret
```

```json
{
  "servers": [
    {
      "name": "api-server",
      "transport": "http",
      "url": "https://api.example.com",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  ]
}
```

You can also provide default values with `${VAR_NAME:-default}` syntax.

### Advanced Configuration Options

#### OAuth 2.0 Authentication

```json
{
  "name": "github-api",
  "transport": "http",
  "url": "https://api.github.com/mcp",
  "auth": {
    "type": "oauth",
    "authorization_url": "https://github.com/login/oauth/authorize",
    "token_url": "https://github.com/login/oauth/access_token",
    "client_id": "your-client-id",
    "client_secret": "${OAUTH_CLIENT_SECRET}",
    "scope": "repo read:user",
    "redirect_uri": "http://localhost:8080/callback"
  }
}
```

#### Connection Retry Configuration

```json
{

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [intertwine](https://github.com/intertwine)
- **Source:** [intertwine/vertex-mcp-chatbot](https://github.com/intertwine/vertex-mcp-chatbot)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-intertwine-vertex-mcp-chatbot
- Seller: https://agentstack.voostack.com/s/intertwine
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.