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

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:

Variable	Description
APP_KEY	Run php artisan key:generate after container starts
API_BASE_URL	AdminV2 backend API URL (e.g. https://admin-backend-api)
LLM_PROVIDER	LLM provider to use: bedrock, openai, anthropic, openrouter, or ollama

LLM Provider Configuration

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

Provider	Variable	Description
bedrock	AWS_ACCESS_KEY_ID	AWS access key
	AWS_SECRET_ACCESS_KEY	AWS secret key
	AWS_BEDROCK_REGION	AWS region (default: us-east-1)
	AWS_BEDROCK_MODEL	Model ID or inference profile ARN
openai	OPENAI_API_KEY	OpenAI API key
	OPENAI_MODEL	Model name (default: gpt-4o-mini)
	OPENAI_BASE_URL	API base URL (default: https://api.openai.com/v1)
anthropic	ANTHROPIC_API_KEY	Anthropic API key
	ANTHROPIC_MODEL	Model name (default: claude-sonnet-4-20250514)
ollama	OLLAMA_BASE_URL	Ollama server URL (default: http://localhost:11434)
	OLLAMA_MODEL	Model name (default: llama3)
openrouter	OPENROUTER_API_KEY	OpenRouter API key
	OPENROUTER_MODEL	Model name (default: qwen/qwen-2.5-72b-instruct)
	OPENROUTER_BASE_URL	API base URL (default: https://openrouter.ai/api/v1)

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": "[email protected]", "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

Container	Image	Port	Purpose
adminv2mcp	Custom (PHP 8.4)	9896	MCP Laravel server
adminv2mcp-mysql	mysql:8.4	3308	Self-learning storage

Stopping

docker compose down

To also remove the database volume:

docker compose down -v