SwEng26_Group19_IBM_MCP_Conversational_Gateway

Getting started

To make it easy for you to get started with GitLab, here's a list of recommended next steps.

Already a pro? Just edit this README.md and make it your own. Want to make it easy? Use the template at the bottom!

Add your files

Create or upload files
Add files using the command line or push an existing Git repository with the following command:

cd existing_repo
git remote add origin https://gitlab.scss.tcd.ie/aodonne8/sweng26_group19_ibm_mcp_conversational_gateway.git
git branch -M main
git push -uf origin main

Integrate with your tools

Set up project integrations

Collaborate with your team

Test and Deploy

Use the built-in continuous integration in GitLab.

Editing this README

When you're ready to make this README your own, just edit this file and use the handy template below (or feel free to structure it however you want - this is just a starting point!). Thanks to makeareadme.com for this template.

Suggestions for a good README

Every project is different, so consider which of these sections apply to yours. The sections used in the template are suggestions for most open source projects. Also keep in mind that while a README can be too long and detailed, too long is better than too short. If you think your README is too long, consider utilizing another form of documentation rather than cutting out information.

Name

Choose a self-explaining name for your project.

Description

Let people know what your project can do specifically. Provide context and add a link to any reference visitors might be unfamiliar with. A list of Features or a Background subsection can also be added here. If there are alternatives to your project, this is a good place to list differentiating factors.

Badges

On some READMEs, you may see small images that convey metadata, such as whether or not all the tests are passing for the project. You can use Shields to add some to your README. Many services also have instructions for adding a badge.

Optional: background it

Start-Process -FilePath "mcpgateway.exe" -ArgumentList "--host 0.0.0.0 --port 4444"

4️⃣ Bearer token and smoke-test

$Env:MCPGATEWAY_BEARER_TOKEN = python3 -m mcpgateway.utils.create_jwt_token ` --username admin@example.com --exp 10080 --secret my-test-key

curl -s -H "Authorization: Bearer $Env:MCPGATEWAY_BEARER_TOKEN" ` http://127.0.0.1:4444/version | jq


<details>
<summary><strong>⚡ Alternative: uv (faster)</strong></summary>

```powershell
# 1️⃣  Isolated env + install from PyPI using uv
mkdir mcpgateway ; cd mcpgateway
uv venv
.\.venv\Scripts\activate
uv pip install mcp-contextforge-gateway

# Continue with steps 2️⃣-4️⃣ above...

More configuration

Copy .env.example to .env and tweak any of the settings (or use them as env variables).

🚀 End-to-end demo (register a local MCP server)

# 1️⃣  Spin up the sample GO MCP time server using mcpgateway.translate & docker (replace docker with podman if needed)
python3 -m mcpgateway.translate \
     --stdio "docker run --rm -i ghcr.io/ibm/fast-time-server:latest -transport=stdio" \
     --expose-sse \
     --port 8003

# Or using the official mcp-server-git using uvx:
pip install uv # to install uvx, if not already installed
python3 -m mcpgateway.translate --stdio "uvx mcp-server-git" --expose-sse --port 9000

# Alternative: running the local binary
# cd mcp-servers/go/fast-time-server; make build
# python3 -m mcpgateway.translate --stdio "./dist/fast-time-server -transport=stdio" --expose-sse --port 8002

# NEW: Expose via multiple protocols simultaneously!
python3 -m mcpgateway.translate \
     --stdio "uvx mcp-server-git" \
     --expose-sse \
     --expose-streamable-http \
     --port 9000
# Now accessible via both /sse (SSE) and /mcp (streamable HTTP) endpoints

# 2️⃣  Register it with the gateway
curl -s -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"name":"fast_time","url":"http://localhost:8003/sse"}' \
     http://localhost:4444/gateways

# 3️⃣  Verify tool catalog
curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/tools | jq

# 4️⃣  Create a *virtual server* bundling those tools. Use the ID of tools from the tool catalog (Step #3) and pass them in the associatedTools list.
curl -s -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"server":{"name":"time_server","description":"Fast time tools","associated_tools":[<ID_OF_TOOLS>]}}' \
     http://localhost:4444/servers | jq

# Example curl
curl -s -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN"
     -H "Content-Type: application/json"
     -d '{"server":{"name":"time_server","description":"Fast time tools","associated_tools":["6018ca46d32a4ac6b4c054c13a1726a2"]}}' \
     http://localhost:4444/servers | jq

# 5️⃣  List servers (should now include the UUID of the newly created virtual server)
curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/servers | jq

# 6️⃣  Client HTTP endpoint. Inspect it interactively with the MCP Inspector CLI (or use any MCP client)
npx -y @modelcontextprotocol/inspector
# Transport Type: Streamable HTTP, URL: http://localhost:4444/servers/UUID_OF_SERVER_1/mcp,  Header Name: "Authorization", Bearer Token

🖧 Using the stdio wrapper (mcpgateway-wrapper)

export MCP_AUTH="Bearer ${MCPGATEWAY_BEARER_TOKEN}"
export MCP_SERVER_URL=http://localhost:4444/servers/UUID_OF_SERVER_1/mcp
python3 -m mcpgateway.wrapper  # Ctrl-C to exit

You can also run it with uv or inside Docker/Podman - see the Containers section above.

In MCP Inspector, define MCP_AUTH and MCP_SERVER_URL env variables, and select python3 as the Command, and -m mcpgateway.wrapper as Arguments.

echo $PWD/.venv/bin/python3 # Using the Python3 full path ensures you have a working venv
export MCP_SERVER_URL='http://localhost:4444/servers/UUID_OF_SERVER_1/mcp'
export MCP_AUTH="Bearer ${MCPGATEWAY_BEARER_TOKEN}"
npx -y @modelcontextprotocol/inspector

or

Pass the url and auth as arguments (no need to set environment variables)

npx -y @modelcontextprotocol/inspector
command as `python`
Arguments as `-m mcpgateway.wrapper --url "http://localhost:4444/servers/UUID_OF_SERVER_1/mcp" --auth "Bearer <your token>"`

When using a MCP Client such as Claude with stdio:

{
  "mcpServers": {
    "mcpgateway-wrapper": {
      "command": "python",
      "args": ["-m", "mcpgateway.wrapper"],
      "env": {
        "MCP_AUTH": "Bearer your-token-here",
        "MCP_SERVER_URL": "http://localhost:4444/servers/UUID_OF_SERVER_1",
        "MCP_TOOL_CALL_TIMEOUT": "120"
      }
    }
  }
}

Quick Start - Containers

Use the official OCI image from GHCR with Docker or Podman. Please note: Currently, arm64 is not supported on production. If you are e.g. running on MacOS with Apple Silicon chips (M1, M2, etc), you can run the containers using Rosetta or install via PyPi instead.

🚀 Quick Start - Docker Compose

Get a full stack running with MariaDB and Redis in under 30 seconds:

# Clone and start the stack
git clone https://github.com/IBM/mcp-context-forge.git
cd mcp-context-forge

# Start with MariaDB (recommended for production)
docker compose up -d

# Or start with PostgreSQL
# Uncomment postgres in docker-compose.yml and comment mariadb section
# docker compose up -d

# Check status
docker compose ps

# View logs
docker compose logs -f gateway

# Access Admin UI: http://localhost:4444/admin (login with PLATFORM_ADMIN_EMAIL/PASSWORD)
# Generate API token
docker compose exec gateway python3 -m mcpgateway.utils.create_jwt_token \
  --username admin@example.com --exp 10080 --secret my-test-key

What you get:

🗄️ MariaDB 10.6 - Production-ready database with 36+ tables
🚀 ContextForge - Full-featured gateway with Admin UI
📊 Redis - High-performance caching and session storage
🔧 Admin Tools - pgAdmin, Redis Insight for database management
🌐 Nginx Proxy - Caching reverse proxy (optional)

Enable HTTPS (optional):

# Start with TLS enabled (auto-generates self-signed certs)
make compose-tls

# Access via HTTPS: https://localhost:8443/admin

# Or bring your own certificates:
# Unencrypted key:
mkdir -p certs
cp your-cert.pem certs/cert.pem && cp your-key.pem certs/key.pem
make compose-tls

# Passphrase-protected key:
mkdir -p certs
cp your-cert.pem certs/cert.pem && cp your-encrypted-key.pem certs/key-encrypted.pem
echo "KEY_FILE_PASSWORD=your-passphrase" >> .env
make compose-tls

☸️ Quick Start - Helm (Kubernetes)

Deploy to Kubernetes with enterprise-grade features:

# Add Helm repository (when available)
# helm repo add mcp-context-forge https://ibm.github.io/mcp-context-forge
# helm repo update

# For now, use local chart
git clone https://github.com/IBM/mcp-context-forge.git
cd mcp-context-forge/charts/mcp-stack

# Install with MariaDB
helm install mcp-gateway . \
  --set mcpContextForge.secret.PLATFORM_ADMIN_EMAIL=admin@yourcompany.com \
  --set mcpContextForge.secret.PLATFORM_ADMIN_PASSWORD=changeme \
  --set mcpContextForge.secret.JWT_SECRET_KEY=your-secret-key \
  --set postgres.enabled=false \
  --set mariadb.enabled=true

# Or install with PostgreSQL (default)
helm install mcp-gateway . \
  --set mcpContextForge.secret.PLATFORM_ADMIN_EMAIL=admin@yourcompany.com \
  --set mcpContextForge.secret.PLATFORM_ADMIN_PASSWORD=changeme \
  --set mcpContextForge.secret.JWT_SECRET_KEY=your-secret-key

# Check deployment status
kubectl get pods -l app.kubernetes.io/name=mcp-context-forge

# Port forward to access Admin UI
kubectl port-forward svc/mcp-gateway-mcp-context-forge 4444:80
# Access: http://localhost:4444/admin

# Generate API token
kubectl exec deployment/mcp-gateway-mcp-context-forge -- \
  python3 -m mcpgateway.utils.create_jwt_token \
  --username admin@yourcompany.com --exp 10080 --secret your-secret-key

SSRF note: Helm defaults to strict SSRF settings (SSRF_ALLOW_PRIVATE_NETWORKS=false). If you register in-cluster tool URLs (for example fast-time or fast-test services), allow only your cluster CIDRs via mcpContextForge.config.SSRF_ALLOWED_NETWORKS or, for local-only benchmark setups, temporarily set SSRF_ALLOW_PRIVATE_NETWORKS=true. See docs/docs/manage/configuration.md#ssrf-protection and docs/docs/deployment/helm.md.

Enterprise Features:

🔄 Auto-scaling - HPA with CPU/memory targets
🗄️ Database Choice - PostgreSQL, MariaDB, or MySQL
📊 Observability - Prometheus metrics, OpenTelemetry tracing
🔒 Security - RBAC, network policies, secret management
🚀 High Availability - Multi-replica deployments with Redis clustering
📈 Monitoring - Built-in Grafana dashboards and alerting

🐳 Docker (Single Container)

docker run -d --name mcpgateway \
  -p 4444:4444 \
  -e MCPGATEWAY_UI_ENABLED=true \
  -e MCPGATEWAY_ADMIN_API_ENABLED=true \
  -e HOST=0.0.0.0 \
  -e JWT_SECRET_KEY=my-test-key \
  -e AUTH_REQUIRED=true \
  -e PLATFORM_ADMIN_EMAIL=admin@example.com \
  -e PLATFORM_ADMIN_PASSWORD=changeme \
  -e PLATFORM_ADMIN_FULL_NAME="Platform Administrator" \
  -e DATABASE_URL=sqlite:///./mcp.db \
  -e SECURE_COOKIES=false \
  ghcr.io/ibm/mcp-context-forge:1.0.0-RC-2

# Tail logs and generate API key
docker logs -f mcpgateway
docker run --rm -it ghcr.io/ibm/mcp-context-forge:1.0.0-RC-2 \
  python3 -m mcpgateway.utils.create_jwt_token --username admin@example.com --exp 10080 --secret my-test-key

Browse to http://localhost:4444/admin and login with PLATFORM_ADMIN_EMAIL / PLATFORM_ADMIN_PASSWORD.

Advanced: Persistent storage, host networking, airgapped

Persist SQLite database:

mkdir -p $(pwd)/data && touch $(pwd)/data/mcp.db && chmod 777 $(pwd)/data
docker run -d --name mcpgateway --restart unless-stopped \
  -p 4444:4444 -v $(pwd)/data:/data \
  -e DATABASE_URL=sqlite:////data/mcp.db \
  -e MCPGATEWAY_UI_ENABLED=true -e MCPGATEWAY_ADMIN_API_ENABLED=true \
  -e HOST=0.0.0.0 -e JWT_SECRET_KEY=my-test-key \
  -e PLATFORM_ADMIN_EMAIL=admin@example.com -e PLATFORM_ADMIN_PASSWORD=changeme \
  ghcr.io/ibm/mcp-context-forge:1.0.0-RC-2

Host networking (access local MCP servers):

docker run -d --name mcpgateway --network=host \
  -v $(pwd)/data:/data -e DATABASE_URL=sqlite:////data/mcp.db \
  -e MCPGATEWAY_UI_ENABLED=true -e HOST=0.0.0.0 -e PORT=4444 \
  ghcr.io/ibm/mcp-context-forge:1.0.0-RC-2

Airgapped deployment (no internet):

docker build -f Containerfile.lite -t mcpgateway:airgapped .
docker run -d --name mcpgateway -p 4444:4444 \
  -e MCPGATEWAY_UI_AIRGAPPED=true -e MCPGATEWAY_UI_ENABLED=true \
  -e HOST=0.0.0.0 -e JWT_SECRET_KEY=my-test-key \
  mcpgateway:airgapped

🦭 Podman (rootless-friendly)

podman run -d --name mcpgateway \
  -p 4444:4444 -e HOST=0.0.0.0 -e DATABASE_URL=sqlite:///./mcp.db \
  ghcr.io/ibm/mcp-context-forge:1.0.0-RC-2

Advanced: Persistent storage, host networking

Persist SQLite:

mkdir -p $(pwd)/data && chmod 777 $(pwd)/data
podman run -d --name mcpgateway --restart=on-failure \
  -p 4444:4444 -v $(pwd)/data:/data \
  -e DATABASE_URL=sqlite:////data/mcp.db \
  ghcr.io/ibm/mcp-context-forge:1.0.0-RC-2

Host networking:

podman run -d --name mcpgateway --network=host \
  -v $(pwd)/data:/data -e DATABASE_URL=sqlite:////data/mcp.db \
  ghcr.io/ibm/mcp-context-forge:1.0.0-RC-2

✏️ Docker/Podman tips

.env files - Put all the -e FOO= lines into a file and replace them with --env-file .env. See the provided .env.example for reference.
Pinned tags - Use an explicit version (e.g. 1.0.0-RC-2) instead of latest for reproducible builds.

JWT tokens - Generate one in the running container:

docker exec mcpgateway python3 -m mcpgateway.utils.create_jwt_token --username admin@example.com --exp 10080 --secret my-test-key

Upgrades - Stop, remove, and rerun with the same -v $(pwd)/data:/data mount; your DB and config stay intact.

🚑 Smoke-test the running container

curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
     http://localhost:4444/health | jq
curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
     http://localhost:4444/tools | jq
curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
     http://localhost:4444/version | jq

🖧 Running ContextForge stdio wrapper

The mcpgateway.wrapper lets you connect to the gateway over stdio while keeping JWT authentication. You should run this from the MCP Client. The example below is just for testing.

# Set environment variables
export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token --username admin@example.com --exp 10080 --secret my-test-key)
export MCP_AUTH="Bearer ${MCPGATEWAY_BEARER_TOKEN}"
export MCP_SERVER_URL='http://localhost:4444/servers/UUID_OF_SERVER_1/mcp'
export MCP_TOOL_CALL_TIMEOUT=120
export MCP_WRAPPER_LOG_LEVEL=DEBUG  # or OFF to disable logging

docker run --rm -i \
  -e MCP_AUTH=$MCP_AUTH \
  -e MCP_SERVER_URL=http://host.docker.internal:4444/servers/UUID_OF_SERVER_1/mcp \
  -e MCP_TOOL_CALL_TIMEOUT=120 \
  -e MCP_WRAPPER_LOG_LEVEL=DEBUG \
  ghcr.io/ibm/mcp-context-forge:1.0.0-RC-2 \
  python3 -m mcpgateway.wrapper

Quick Start: VS Code Dev Container

Clone the repo and open in VS Code—it will detect .devcontainer and prompt to "Reopen in Container". The container includes Python 3.11, Docker CLI, and all project dependencies.

For detailed setup, workflows, and GitHub Codespaces instructions, see Developer Onboarding.

Installation

Within a particular ecosystem, there may be a common way of installing things, such as using Yarn, NuGet, or Homebrew. However, consider the possibility that whoever is reading your README is a novice and would like more guidance. Listing specific steps helps remove ambiguity and gets people to using your project as quickly as possible. If it only runs in a specific context like a particular programming language version or operating system or has dependencies that have to be installed manually, also add a Requirements subsection.

Usage

Use examples liberally, and show the expected output if you can. It's helpful to have inline the smallest example of usage that you can demonstrate, while providing links to more sophisticated examples if they are too long to reasonably include in the README.

Support

Tell people where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc.

Roadmap

If you have ideas for releases in the future, it is a good idea to list them in the README.

Contributing

State if you are open to contributions and what your requirements are for accepting them.

For people who want to make changes to your project, it's helpful to have some documentation on how to get started. Perhaps there is a script that they should run or some environment variables that they need to set. Make these steps explicit. These instructions could also be useful to your future self.

You can also document commands to lint the code or run tests. These steps help to ensure high code quality and reduce the likelihood that the changes inadvertently break something. Having instructions for running tests is especially helpful if it requires external setup, such as starting a Selenium server for testing in a browser.

Authors and acknowledgment

Show your appreciation to those who have contributed to the project.

License

For open source projects, say how it is licensed.

Project status

If you have run out of energy or time for your project, put a note at the top of the README saying that development has slowed down or stopped completely. Someone may choose to fork your project or volunteer to step in as a maintainer or owner, allowing your project to keep going. You can also make an explicit request for maintainers.

Name		Name	Last commit message	Last commit date
Latest commit History 4,837 Commits
.devcontainer		.devcontainer
.github		.github
a2a-agents/go/a2a-echo-agent		a2a-agents/go/a2a-echo-agent
agent_runtimes/langchain_agent		agent_runtimes/langchain_agent
charts		charts
deployment		deployment
docs		docs
examples		examples
infra		infra
llms		llms
mcp-servers		mcp-servers
mcpgateway		mcpgateway
plugin_templates		plugin_templates
plugins		plugins
plugins_rust		plugins_rust
scripts		scripts
tests		tests
tools_rust/wrapper		tools_rust/wrapper
.bumpversion.cfg		.bumpversion.cfg
.darglint		.darglint
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.env.ce.example		.env.ce.example
.env.example		.env.example
.env.make		.env.make
.flake8		.flake8
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitlab-ci.yml		.gitlab-ci.yml
.hadolint.yaml		.hadolint.yaml
.htmlhintrc		.htmlhintrc
.jshintrc		.jshintrc
.markdownlint-cli2.yaml		.markdownlint-cli2.yaml
.nvim.lua		.nvim.lua
.pre-commit-config.yaml		.pre-commit-config.yaml
.pre-commit-lite.yaml		.pre-commit-lite.yaml
.prospector.yaml		.prospector.yaml
.pycodestyle		.pycodestyle
.pylintrc		.pylintrc
.pyspelling.yml		.pyspelling.yml
.snyk		.snyk
.spellcheck-en.txt		.spellcheck-en.txt
.stylelintrc.json		.stylelintrc.json
.travis.yml		.travis.yml
.whitesource		.whitesource
.yamllint		.yamllint
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
COLLABORATIVE_FILTERING.md		COLLABORATIVE_FILTERING.md
CONTRIBUTING.md		CONTRIBUTING.md
Containerfile		Containerfile
Containerfile.lite		Containerfile.lite
Containerfile.scratch		Containerfile.scratch
DCO.txt		DCO.txt
DEVELOPING.md		DEVELOPING.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
MIGRATION-0.7.0.md		MIGRATION-0.7.0.md
MULTIPLATFORM.md		MULTIPLATFORM.md
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
TESTING.md		TESTING.md
_analyze_migrations.py		_analyze_migrations.py
compose.upgrade.yml		compose.upgrade.yml
conftest.py		conftest.py
copier.yml		copier.yml
docker-compose-debug.yml		docker-compose-debug.yml
docker-compose-embedded.yml		docker-compose-embedded.yml
docker-compose-performance.yml		docker-compose-performance.yml
docker-compose-verbose-logging.yml		docker-compose-verbose-logging.yml
docker-compose.mariadb.yml		docker-compose.mariadb.yml
docker-compose.override.lite.yml		docker-compose.override.lite.yml
docker-compose.phoenix-simple.yml		docker-compose.phoenix-simple.yml
docker-compose.sso.yml		docker-compose.sso.yml
docker-compose.with-phoenix.yml		docker-compose.with-phoenix.yml
docker-compose.yml		docker-compose.yml
docker-entrypoint.sh		docker-entrypoint.sh
enable_payload_logging.md		enable_payload_logging.md
eslint.config.js		eslint.config.js
fly.toml		fly.toml
gunicorn.config.py		gunicorn.config.py
license-policy.toml		license-policy.toml
mcp-catalog.yml		mcp-catalog.yml
migration_add_annotations.py		migration_add_annotations.py
mutmut_config.py		mutmut_config.py
os_deps.sh		os_deps.sh
package-lock.json		package-lock.json
package.json		package.json
playwright.config.py		playwright.config.py
podman-compose-sonarqube.yaml		podman-compose-sonarqube.yaml
pyproject.toml		pyproject.toml
pyrightconfig.json		pyrightconfig.json
run-granian.sh		run-granian.sh
run-gunicorn.sh		run-gunicorn.sh
run.sh		run.sh
run_mutmut.py		run_mutmut.py
semgrep.yml		semgrep.yml

Folders and files

Latest commit

History

Repository files navigation

SwEng26_Group19_IBM_MCP_Conversational_Gateway

Getting started

Add your files

Integrate with your tools

Collaborate with your team

Test and Deploy

Editing this README

Suggestions for a good README

Name

Description

Badges

Optional: background it

Start-Process -FilePath "mcpgateway.exe" -ArgumentList "--host 0.0.0.0 --port 4444"

4️⃣ Bearer token and smoke-test

Quick Start - Containers

🚀 Quick Start - Docker Compose

☸️ Quick Start - Helm (Kubernetes)

🐳 Docker (Single Container)

🦭 Podman (rootless-friendly)

Quick Start: VS Code Dev Container

Installation

Usage

Support

Roadmap

Contributing

Authors and acknowledgment

License

Project status

About

Resources

License

Licenses found

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages