# Enterprise BAU Services with MCP and Gemini

An executable proof of concept showing how an AI agent can work with existing Business-as-Usual (BAU) REST microservices through the Model Context Protocol (MCP).

The demonstration uses Google Gemini to discover MCP tools, retrieve customer and order information, and perform a controlled order-cancellation action. The BAU services remain independent REST APIs; MCP provides the integration boundary between those APIs and the agent.

## Demonstration

The included scenario asks the agent to:

1. Retrieve the profile for `CUST-1001`.
2. List the customer's orders.
3. Identify the order in `Processing` status.
4. Cancel `ORD-9002` with a supplied reason.
5. Summarize the completed work.

The expected tool sequence is:

```text
Gemini agent
    -> MCP tool discovery over stdio
    -> MCP server
    -> Customer and Order REST APIs
    -> Tool results returned to Gemini
    -> Final user-facing summary
```

## Architecture

```text
+------------------+       stdio        +------------------+       HTTP       +----------------------+
| Gemini agent     | <----------------> | MCP server       | <--------------> | Customer service     |
| agent_runner.py  |                    | server.py        |                  | localhost:8001       |
+------------------+                    +--------+---------+                  +----------------------+
                                                   |
                                                   | HTTP
                                                   v
                                         +----------------------+
                                         | Order service        |
                                         | localhost:8002       |
                                         +----------------------+
```

### MCP tools

| Tool | Purpose |
| --- | --- |
| `get_customer_profile` | Retrieves customer profile, tier, status, and credit limit. |
| `get_customer_orders` | Lists orders associated with a customer. |
| `cancel_order_by_id` | Cancels an order when its status allows cancellation. |

## Project structure

```text
.
├── agent/
│   └── agent_runner.py          # Gemini agent and MCP client
├── mcp_server/
│   └── server.py                # MCP tools and REST integration
├── services/
│   ├── customer_service.py      # Mock customer REST API
│   └── order_service.py         # Mock order REST API
├── tests/
│   └── test_services.py         # Service behavior tests
├── .env.example                 # Environment variable template
├── requirements.txt             # Python dependencies
└── mcp_microservices_poc_blueprint.md
                                # Detailed design and implementation reference
```

## Prerequisites

- Python 3.11 or newer
- A Gemini API key from Google AI Studio
- Windows PowerShell, macOS/Linux shell, or an equivalent terminal
- Network access to the Gemini API when running the agent

This project does not require an Anthropic or OpenAI API key.

## Quick start on Windows

Open PowerShell in the project directory:

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
Copy-Item .env.example .env
```

Open `.env` and replace `your_gemini_api_key_here` with your key:

```env
GOOGLE_API_KEY=your_gemini_api_key_here
GEMINI_MODEL=gemini-3.6-flash
```

Never commit `.env` or place an API key in source code. The selected model must be available to your Gemini account.

## Run the demonstration

Use three terminals. Activate `.venv` in each terminal.

### Terminal 1: customer service

```powershell
python services/customer_service.py
```

Runs at `http://localhost:8001`.

### Terminal 2: order service

```powershell
python services/order_service.py
```

Runs at `http://localhost:8002`.

### Terminal 3: Gemini agent

```powershell
python agent/agent_runner.py
```

The agent starts the MCP server as a child process, discovers its tools, and executes the sample workflow.

## Verify the local services

Run these commands while the two services are active:

```powershell
Invoke-RestMethod http://localhost:8001/health
Invoke-RestMethod http://localhost:8002/health
Invoke-RestMethod http://localhost:8001/api/v1/customers/CUST-1001
Invoke-RestMethod http://localhost:8002/api/v1/orders/customer/CUST-1001
```

## Run the tests

With the virtual environment active:

```powershell
python -m pytest -q
```

The tests cover case-insensitive customer lookup, missing customers, cancellation of a processing order, and protection against cancelling a shipped order.

## Configuration

| Variable | Description | Default |
| --- | --- | --- |
| `GOOGLE_API_KEY` | Gemini authentication key. | Required |
| `GEMINI_MODEL` | Gemini model used by the agent. | `gemini-3.6-flash` |
| `CUSTOMER_SERVICE_URL` | Customer service base URL. | `http://localhost:8001` |
| `ORDER_SERVICE_URL` | Order service base URL. | `http://localhost:8002` |

## Scope and limitations

This is a local, intentionally small POC intended to make the integration pattern easy to inspect and run.

- Customer and order records are stored in memory and reset when services restart.
- The services do not implement authentication or authorization.
- The cancellation operation should be protected by approval and business policy controls in a real system.
- MCP uses stdio for local process integration. A deployed architecture should use an authenticated network transport.
- Downstream errors are returned as tool text for visibility; production systems should use structured errors, retries, tracing, and metrics.
- The sample agent makes a real Gemini API request and requires a valid key.

## Troubleshooting

### `GOOGLE_API_KEY is not set`

Confirm that `.env` exists in the project directory and contains a valid key. Run the agent from the project directory.

### `404 NOT_FOUND` for a Gemini model

Set `GEMINI_MODEL` in `.env` to a model enabled for your account. The default in this POC is `gemini-3.6-flash`.

### MCP startup or tool discovery fails

Confirm that dependencies were installed into the active virtual environment:

```powershell
python -m pip install -r requirements.txt
```

The project pins MCP to the `1.x` API range because the server implementation uses `FastMCP`.

### Connection errors from MCP tools

Confirm both REST services are running on ports `8001` and `8002`. If a port is already in use, update the service port and the matching URL in `.env`.

## Further reading

- [LLM access details](llm_access_details.md)
- [Detailed POC blueprint](mcp_microservices_poc_blueprint.md)