Workspace MCP Server

An MCP (Model Context Protocol) server that gives AI agents read-time access to workspace databases and project management APIs.

Built with FastMCP, this service acts as a universal data gateway — allowing any MCP-compatible agent (Claude Desktop, Copilot, custom orchestrators) to introspect, query, and correlate business data without writing integration code.

Architecture & Stack Rationale

Why MCP + FastMCP?

Model Context Protocol is the emerging standard for connecting LLMs to external tools and data. Instead of building one-off function calls or plugin APIs per agent, MCP provides a single, typed interface that any compliant LLM can discover and invoke at runtime.

• FastMCP was chosen over raw mcp SDK because it eliminates boilerplate: tools are plain Python functions with a decorator — no JSON-RPC wire protocol handling, no manual capability negotiation.

• The SSE (Server-Sent Events) transport allows long-lived connections from agents running in browsers, desktop apps, or cloud functions, and is trivially load-balanced behind Knative or any HTTP ingress.

┌──────────────────────┐     MCP/SSE      ┌──────────────────────────────┐
│  AI Agent            │ ◄──────────────► │  Workspace MCP Server        │
│  (Claude, Copilot…)  │                  │  ├─ Database Tools (Mongo)   │
└──────────────────────┘                  │  └─ API Tools (REST)         │
                                          └──────────────────────────────┘

Why MongoDB for Workspace Data?

Workspace applications produce semi-structured, schema-flexible data — project documents, task metadata, user activity logs, and configuration records. MongoDB's document model:

• Handles polymorphic schemas without migrations (different document types emit different fields).

• Provides native aggregation pipelines for reporting and analytics (counts, grouping, windowed stats).

• Supports text indexes for full-text search across notes, descriptions, and logs.

• The analyze_database tool gives AI agents runtime introspection — they discover collections, field types, and indexes on their own, without hardcoded schemas.

Why a Dedicated Project Management API Adapter?

The project management REST API tracks tickets, tasks, projects, and users. Rather than exposing raw HTTP to the LLM (security risk + prompt overhead), the server wraps the API with:

• Managed authentication — supports both Bearer token and Basic Auth; credentials never leak into the agent conversation.

• Structured error boundaries — non-2xx responses are captured and returned as strings, never as raw stack traces.

• Metadata tools (get_metadata, get_custom_fields) that let the agent self-discover valid enum values and custom field IDs — no hardcoding, no "I don't know what statuses exist."

Why Knative + Kubernetes for Deployment?

Production workloads demand zero-downtime updates and automatic scaling:

The deploy_kn.sh script handles the full lifecycle: Docker build, image push to private registry, Kubernetes Secret upsert, and Knative Service apply — all in a single idempotent command.

Tools Overview

Database (MongoDB)

Project Management API (REST)

Quick Start

pip install -r requirements.txt

cp .env.example .env
# Edit WORKSPACE_MONGO_URI, API_TOKEN, API_SITE_ID

python server.py

Server starts on http://0.0.0.0:8080 with SSE transport. Connect any MCP client to http://host:8080/sse.

Environment Variables

Docker

docker build -t workspace-mcp .
docker run -p 8080:8080 --env-file .env workspace-mcp

Deployment

export AGENT_NAME=workspace-mcp
export DEPLOYMENT_CONTEXT=workspace
bash deploy.sh

Requires: Docker, kubectl (with Knative Serving installed), access to a container registry, and a .env.workspace file with deployment-specific variables (registry, namespace, pull secret, credentials).