Update docs

crivetimihai · crivetimihai · commit f20143cc179a · 2025-08-23T02:51:14.000+01:00
Signed-off-by: Mihai Criveti &lt;crivetimihai@gmail.com&gt;
diff --git a/docs/docs/best-practices/developing-your-mcp-server-python.md b/docs/docs/best-practices/developing-your-mcp-server-python.md
@@ -125,7 +125,7 @@ curl -X POST http://127.0.0.1:4444/gateways \
   -d '{"name":"my_echo_server","url":"http://127.0.0.1:8000/mcp","transport":"streamablehttp"}'
 ```
 
-For instructions on registering your server via the UI, please see [Register with the Gateway UI](register-server.md#registering-a-tool-with-the-gateway).
+For instructions on registering your server via the UI, please see [Gateway Integration](../using/servers/index.md#gateway-integration).
 
 ### 4.2 Verify Registration
 
diff --git a/docs/docs/deployment/index.md b/docs/docs/deployment/index.md
@@ -43,7 +43,7 @@ MCP Gateway loads configuration from:
 - Environment variables (overrides `.env`)
 - CLI flags (e.g., via `run.sh`)
 
-⚠️ **Security Note**: Never store sensitive credentials directly in environment variables. Use a secrets management system in production. See the [Security Guide](../manage/securing.md#secrets-management) for details.
+⚠️ **Security Note**: Never store sensitive credentials directly in environment variables. Use a secrets management system in production. See the [Security Guide](../manage/securing.md#5-secrets-management) for details.
 
 ---
 
@@ -70,4 +70,4 @@ The default container image:
 
 > For Kubernetes, you can mount a ConfigMap or Secret as `.env`.
 
-**Important**: For production deployments, ensure you follow the container hardening guidelines in our [Security Guide](../manage/securing.md#container-security).
+**Important**: For production deployments, ensure you follow the container hardening guidelines in our [Security Guide](../manage/securing.md#4-container-security).
diff --git a/docs/docs/development/doctest-coverage.md b/docs/docs/development/doctest-coverage.md
@@ -328,4 +328,4 @@ python -m py_compile module.py
 - [Development Guide](index.md) - General development information
 - [Testing Guide](../testing/index.md) - Testing strategies and tools
 - [Contributing Guidelines](https://github.com/IBM/mcp-context-forge/blob/main/CONTRIBUTING.md) - How to contribute to the project
-- [Makefile Targets](../../../README.md#makefile-targets) - Available make targets including doctest commands
+- [Makefile Targets](../index.md#makefile-targets) - Available make targets including doctest commands
diff --git a/docs/docs/development/mcp-developer-guide-json-rpc.md b/docs/docs/development/mcp-developer-guide-json-rpc.md
@@ -1170,4 +1170,4 @@ module.exports = MCPGatewayClient;
 - [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification)
 - [MCP Gateway Documentation](https://ibm.github.io/mcp-context-forge/)
 - [MCP Gateway Admin UI Guide](../manage/index.md)
-- [MCP Gateway Wrapper Documentation](mcpgateway-wrapper.md)
+- [MCP Gateway Wrapper Documentation](../using/mcpgateway-wrapper.md)
diff --git a/docs/docs/faq/index.md b/docs/docs/faq/index.md
@@ -263,7 +263,7 @@
 ## 🤝 Contributing & Community
 
 ???+ tip "👩💻 How can I file issues or contribute?"
-    Use [GitHub Issues](https://github.com/IBM/mcp-context-forge/issues) and `CONTRIBUTING.md`.
+    Use [GitHub Issues](https://github.com/IBM/mcp-context-forge/issues) and [CONTRIBUTING.md](https://github.com/IBM/mcp-context-forge/blob/main/CONTRIBUTING.md).
 
 ???+ tip "🧑🎓 What code style and CI tools are used?"
     - Pre-commit: `ruff`, `black`, `mypy`, `isort`
diff --git a/docs/docs/index.md b/docs/docs/index.md
diff --git a/docs/docs/manage/export-import-tutorial.md b/docs/docs/manage/export-import-tutorial.md
@@ -382,4 +382,4 @@ If you encounter issues:
 4. **Use dry-run**: Always validate imports before applying changes
 5. **Check authentication**: Verify tokens and encryption keys are correct
 
-For detailed troubleshooting, see the main [Export & Import Guide](export-import.md#-troubleshooting).
+For detailed troubleshooting, see the main [Export & Import Guide](export-import.md).
diff --git a/docs/docs/manage/proxy.md b/docs/docs/manage/proxy.md
@@ -662,7 +662,7 @@ SESSION_TTL=3600  # 1 hour
 
 ## Related Documentation
 
-- [Authentication Overview](../authentication.md)
-- [Security Best Practices](../security.md)
+- [Authentication Overview](./securing.md)
+- [Security Best Practices](../architecture/security-features.md)
 - [Deployment Guide](../deployment/index.md)
-- [Federation Setup](../federation.md)
+- [Federation Setup](../architecture/index.md)
diff --git a/docs/docs/manage/securing.md b/docs/docs/manage/securing.md
@@ -242,7 +242,7 @@ MCPGATEWAY_LOG_SENSITIVE_DATA=false     # Never log sensitive data
 
 - [Security Policy](https://github.com/IBM/mcp-context-forge/blob/main/SECURITY.md) - Full security documentation
 - [Deployment Options](index.md) - Various deployment methods
-- [Environment Variables](../configuration/environment-variables.md) - Complete configuration reference
+- [Environment Variables](../index.md#configuration-env-or-env-vars) - Complete configuration reference
 
 ## ⚡ Quick Start Security Commands
 
diff --git a/docs/docs/manage/ui-customization.md b/docs/docs/manage/ui-customization.md
@@ -1510,7 +1510,7 @@ fetch('/metrics/custom', {
 
 ## Related Documentation
 
-- [Admin UI Overview](/overview/ui/) - Basic UI concepts and navigation
-- [Security Configuration](/manage/securing/) - Securing the Admin UI
-- [Performance Tuning](/manage/tuning/) - Optimizing UI performance
-- [API Reference](/api/admin/) - Admin API endpoints
+- [Admin UI Overview](../overview/ui.md) - Basic UI concepts and navigation
+- [Security Configuration](./securing.md) - Securing the Admin UI
+- [Performance Tuning](./tuning.md) - Optimizing UI performance
+- [API Reference](https://ibm.github.io/mcp-context-forge/api/admin/) - Admin API endpoints
diff --git a/docs/docs/overview/tags.md b/docs/docs/overview/tags.md
@@ -734,7 +734,7 @@ async def discover_related(
 
 ## 🔗 Related Documentation
 
-- [REST API Reference](/api/) - Complete API documentation
-- [Admin UI Guide](/overview/ui/) - Using the web interface
-- [Virtual Servers](/concepts/virtual-servers/) - Composing servers with tags
-- [Federation](/concepts/federation/) - Tag-based gateway discovery
+- [REST API Reference](https://ibm.github.io/mcp-context-forge/api/) - Complete API documentation
+- [Admin UI Guide](./ui.md) - Using the web interface
+- [Virtual Servers](../architecture/index.md) - Composing servers with tags
+- [Federation](../architecture/index.md) - Tag-based gateway discovery
diff --git a/docs/docs/using/.pages b/docs/docs/using/.pages
@@ -4,6 +4,7 @@ nav:
   - mcpgateway-translate.md
   - reverse-proxy.md
   - multi-auth-headers.md
+  - tool-annotations.md
   - Clients: clients
   - Agents: agents
   - Servers: servers
diff --git a/docs/docs/using/agents/a2a.md b/docs/docs/using/agents/a2a.md
@@ -223,4 +223,4 @@ Associate A2A agents with virtual servers to:
 
 ---
 
-For more information on MCP Gateway features and configuration, see the [main documentation](../../overview/).
+For more information on MCP Gateway features and configuration, see the [main documentation](../../overview/index.md).
diff --git a/docs/docs/using/mcpgateway-translate.md b/docs/docs/using/mcpgateway-translate.md
@@ -465,8 +465,8 @@ headers = {
 
 - [MCP Gateway Overview](../overview/index.md)
 - [MCP Protocol Specification](https://modelcontextprotocol.io)
-- [Transport Protocols](../architecture/index.md#transports)
-- [Authentication Guide](../manage/authentication.md)
+- [Transport Protocols](../architecture/index.md#system-architecture)
+- [Authentication Guide](../manage/securing.md)
 
 ## Support
 
diff --git a/docs/docs/using/multi-auth-headers.md b/docs/docs/using/multi-auth-headers.md
@@ -184,6 +184,6 @@ The system will automatically convert your configuration to the multi-header for
 ```
 
 ## Related Documentation
-- [Gateway Authentication](./authentication.md)
-- [Security Best Practices](../security/best-practices.md)
-- [API Documentation](../api/gateways.md)
+- [Gateway Authentication](../manage/securing.md)
+- [Security Best Practices](../architecture/security-features.md)
+- [Multi-Auth Headers](./multi-auth-headers.md)
diff --git a/docs/docs/using/reverse-proxy.md b/docs/docs/using/reverse-proxy.md
@@ -360,7 +360,7 @@ class MonitoredReverseProxy(ReverseProxyClient):
 
 ## Related Documentation
 
-- [MCP Gateway Documentation](./README.md)
+- [MCP Gateway Documentation](../index.md)
 - [MCP Protocol Specification](https://modelcontextprotocol.io)
-- [Transport Protocols](./transports.md)
-- [Authentication Guide](./auth.md)
+- [Transport Protocols](../architecture/index.md)
+- [Authentication Guide](../manage/securing.md)
diff --git a/docs/docs/using/servers/go-fast-time-server.md b/docs/docs/using/servers/go-fast-time-server.md
@@ -1293,6 +1293,6 @@ print(f"Converted time: {result['converted_time']}")
 ## Related Resources
 
 - [MCP Protocol Specification](https://modelcontextprotocol.io/)
-- [MCP Gateway Documentation](../gateway/index.md)
+- [MCP Gateway Documentation](../../index.md)
 - [Go MCP SDK](https://github.com/mark3labs/mcp-go)
 - [Time Zone Database](https://www.iana.org/time-zones)
diff --git a/docs/docs/using/servers/index.md b/docs/docs/using/servers/index.md
@@ -196,7 +196,7 @@ We're particularly interested in:
 - [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification)
 
 ### **Gateway Documentation**
-- [MCP Context Forge Gateway](../README.md)
+- [MCP Context Forge Gateway](../../index.md)
 - [mcpgateway.wrapper Usage](../mcpgateway-wrapper.md)
 - [mcpgateway.translate Bridge](../mcpgateway-translate.md)
 
