ADMINV2MCP

A Model Context Protocol (MCP) server that exposes AdminV2 backend API operations as discoverable, callable tools for AI agents. Built with Laravel and AWS Bedrock (Claude).

Prerequisites

• Docker & Docker Compose

• An external Docker network named vpc_rms_cde

• Access to the AdminV2 backend API

• One of the following LLM providers:

  • AWS Bedrock — requires AWS credentials with Bedrock access

  • OpenAI — requires OpenAI API key

  • Anthropic — requires Anthropic API key

  • OpenRouter — free (limited), requires OpenRouter API key (access to 100+ models)

  • Ollama — free, self-hosted, no API key needed

Related MCP server: python-adtech-mcp-server

Quick Start

1. Clone the repository

git clone <your-gitlab-repo-url>
cd ADMINV2MCP

2. Create the external Docker network (if not exists)

docker network create vpc_rms_cde

3. Configure environment

cp .env.example .env

Edit .env and fill in the required values:

LLM Provider Configuration

Set LLM_PROVIDER in .env and fill in the corresponding credentials:

Note: Ollama is free and runs locally. No API key needed — just install Ollama and pull a model. OpenRouter gives access to 100+ models (Qwen, Claude, GPT, Llama, etc.) with a single API key. OpenRouter's free tier has limited rate and model access but is more than enough for our usage.

4. Start containers

docker compose up -d

This starts 2 containers:

• adminv2mcp — Laravel MCP server on port 9896

• adminv2mcp-mysql — MySQL 8.4 on port 3308

5. Generate app key

docker compose exec adminv2mcp php artisan key:generate

6. Run migrations

docker compose exec adminv2mcp php artisan migrate

7. Verify

curl http://localhost:9896/api/health

Should return:

{"success": true, "service": "ADMINV2MCP"}

Usage

Login

curl -X POST http://localhost:9896/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "your@email.com", "password": "pass", "mfa": "123456"}'

Call a tool (natural language)

curl -X POST http://localhost:9896/api/tools/call \
  -H "Content-Type: application/json" \
  -d '{"message": "yo mcp, show me all applications with processing status. just give me first 2 records, order the recs by submission id"}'

Call a tool (structured)

curl -X POST http://localhost:9896/api/tools/call \
  -H "Content-Type: application/json" \
  -d '{"tool": "get_bulk_application_submission", "arguments": {"filter": {"channel": "MB2U_QRPay-Push"}}}'

Documentation

See docs/MCP_TOOLS.md for full API documentation including:

• All available tools and their parameters

• How MCP works (architecture diagrams)

• Self-learning mechanism

• Restrictions and limitations

• Code examples (JavaScript, Python)

Containers

Stopping

docker compose down

To also remove the database volume:

docker compose down -v