Include tool annotations

[onmete]

Problem
The MCP gateway was dropping tool annotation metadata (hints like readOnlyHint, destructiveHint, idempotentHint, etc.) when proxying tools from MCP servers to clients. This resulted in clients receiving None values for all annotation fields, losing important semantic information about tool behavior.

Context
I understand that it's best to open an issue to discuss proposed changes beforehand. However, this PR is more of a byproduct of my experimentation with mcp-context-forge as a potential MCP gateway solution for Red Hat OpenShift Lightspeed.
I'm perfectly okay if you choose to close this PR—I still found the time spent exploring this approach valuable.

Preview of changes

Changes Made

Backend Infrastructure

• Database: Added annotations JSON column to tools table with migration script
• API Schemas: Updated ToolCreate, ToolUpdate, and ToolRead to include annotations field
• Service Layer: Modified ToolService to handle annotations in registration, updates, and queries
• Transport Layer: Updated all transport implementations to pass through annotations correctly
• Data Migration: Created refresh script to update existing tools with current annotations from their MCP servers

Admin UI Enhancements

• Visual Indicators: Added colored badges for standard MCP annotation types:
  📖 Green: readOnlyHint: true
  ⚠️ Red: destructiveHint: true
  🔄 Purple: idempotentHint: true
  🌐 Yellow: openWorldHint: true
• Tool Details: Enhanced tool detail modals to show all annotation information
• Tools Table: Added annotations column with badge indicators
• Edit Forms: Display annotations in edit modals (read-only, sourced from MCP servers)

Testing

• Updated all unit tests to include annotations field
• Fixed test mocks to properly handle annotations parameter

Impact

• MCP clients now receive complete tool metadata including behavioral hints
• Admin interface provides visual cues about tool characteristics
• Maintains full backward compatibility
• Enables better tool selection and usage decisions by AI agents

[onmete]

And I just noticed it is not working as expected. I've added a new MCP server, which contains tool annotations, but I don't see those in the UI. I'll check later, you can discuss if the feature makes sense in the meantime.

[crivetimihai]

This looks awesome, will review & test in detail - there's a merge conflict atm with admin.html, but I love where this is going! The icons are great too.

Will see if I can find some servers with annotations as well to test with - let me know if you have some suggestions.

We also need to coordinate this with #151 which is a massive PR that affects a lot of the same components - which allows us to namespace MCP servers (ex: in case they have tools with overlapping names) - we'll sort that out on merge!

[onmete]

@crivetimihai Cool!
I'm testing this against https://github.com/manusa/kubernetes-mcp-server (contains hints for tools).

[onmete]

Rebased and fixed the issue - missed storing the annotations in db before...

[crivetimihai]

Hello, I did some initial tests with mcp-servers/go/fast-time-server (for some reason time shows up as destructive, but I guess that must be an error in the MCP server I've created).

Will do more testing tomorrow as we figure out how to merge this along #151 - and what to do about Alembic DB migrations. Drafted but NOT tested: #184 for Alembic setup.

Let me know if you plan to do more pushes on this - we'll get this merged once fully tested, and align with the other PRs for Alembic migrations, and include in the upcoming v0.3.0 release (2025-07-08).

Note: As we start to get closer to a 'stable release' and lift the 'Development Status :: 4 - Beta' tag - we'll include changelog notes and documentation on Alembic schema migrations, etc. for breaking changes. We may also consider releasing the configuration Export feature prior (perhaps 0.2.1 - 2025-07-01) to give folks a way to export configs before breaking DB changes - drafted #185.

PR Test Matrix

Automated Checks

❗ DCO — one commit missing Signed-off-by: (you can do this with git commit -s -m)
✅ All other 20 checks pass

---

CLI / Make

❌ make test — 332/333 FAILED tests/unit/mcpgateway/test_ui_version.py::test_admin_ui_contains_version_tab - sqlalchemy.exc.OperationalError: (sqlite3.OperationalError) no such column: tools.annotations -> this is likely due to lacking Alembic DB migrations (we're in the process of implementing these with #151 as well to deal with DB schema changes, so not a deal-breaker and we need to coordinate) with @madhav165's PR
✅ make test — 333/333 pass with a new database
✅ make smoketest # this runs venv, install install-dev docker builds, some tests
✅ make docker-prod docker-run-ssl-host # or podman-.. then run some manual tests..

curl -sk https://localhost:4444/health
curl -sk https://localhost:4444/ready
export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token --username admin --exp 0 --secret my-test-key)
curl -sk -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" https://localhost:4444/version

✅ make dist verify
✅ make devpi-install devpi-init devpi-start devpi-setup-user devpi-upload devpi-test

---

Admin UI & API

✅ Visit:

• /admin/, /redoc/, /docs, /version

✅ Add time MCP Server to Registry :

docker run -p 8080:8080 --rm -it ghcr.io/ibm/fast-time-server:0.2.0
# or cd mcp-servers/go/fast-time-server; make build ...

✅ Tools: Global Tools > get_current_time
✅ Virtual Server: tooltip/checkbox for multiple tool select
✅ Click all tabs
✅ Gateway toggle (deactivate/reactivate)
✅ Tool call: get_current_time
✅ API:

curl -sk -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" https://localhost:4444/version
curl -sk -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" https://localhost:4444/tools

Docker Compose (test with Postgres and Redis)

❗ Change to image: mcpgateway/mcpgateway:latest in docker-compose.yml && make compose-up

gateway-1     | sqlalchemy.exc.ProgrammingError: (psycopg2.errors.UndefinedColumn) column tools.annotations does not exist
gateway-1     | LINE 1: ...eaders, tools.input_schema AS tools_input_schema, tools.anno...

Note: this breaks due to missing DB alembic migrations so need to kill DB and restart:

make compose-stop compose-rm
docker volume rm mcp-context-forge_pgdata
make compose-up compose-logs

Now it works.

🧪 Skipped (for now)

• mcpgateway.translate
• mcpgateway.wrapper stdio mode
• prompt/resource templates (advanced)
• root-level SSE / subscriptions
• SonarQube (make sonar-submit-docker)
• SSE Connection / HTTP connection test

✅ Helm Chart

✅ Other Checks

• 🚀 ArgoCD: Application synced and healthy via Helm Chart

🧪 Skipped (for now)

• mcpgateway.translate
• mcpgateway.wrapper stdio mode
• prompt/resource templates (advanced)
• root-level SSE / subscriptions

[onmete]

Signed-off. No further (feature) pushes here.

[crivetimihai]

Alembic migrations & review in progress - so far merging with main code looks promising:

Smoktest again

# make smoketest -> passed

# make test
Tested this part, issue is: FAILED tests/unit/mcpgateway/test_ui_version.py::test_admin_ui_contains_version_tab - sqlalchemy.exc.OperationalError: (sqlite3.OperationalError) no such column: tools.annotations

After merging with main:

gh pr checkout 176
git pull
git fetch origin
git merge origin/main

[onmete]

Wow, that was fast. Thanks!