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:

Requirement	Solution
Scale to zero when idle	Knative Serving auto-scales down to 0 replicas
Per-environment isolation	Kubernetes Namespace separation
Secret rotation	Pre-deployment `kubectl create secret` from CI/CD
Canary rollouts	Knative revision traffic splitting

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)

Tool	Purpose
`analyze_database`	Introspect databases, collections, indexes, and inferred schemas
`get_sample_documents`	Peek at documents from any collection
`get_distinct_values`	Distinct values and frequency for a field
`query_documents`	Filtered queries with projection and sort
`aggregate_documents`	MongoDB aggregation pipelines
`count_documents`	Document count matching a filter
`search_documents`	Full-text search across documents

Project Management API (REST)

Tool	Purpose
`check_api_connection`	Verify API connectivity and return caller identity
`list_projects`	List all accessible projects
`search_items`	Query items by structured condition
`get_item_detail`	Full detail — linked items, references, comments
`get_metadata`	Discover valid priorities, statuses, categories, projects
`find_user`	Resolve users by name or email
`get_custom_fields`	List custom fields with API IDs

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

Variable	Description
`WORKSPACE_MONGO_URI`	MongoDB connection string
`API_TOKEN`	Project management API token
`API_EMAIL`	Email for Basic Auth (omit for Bearer token)
`API_BASE_URL`	API instance URL
`API_SITE_ID`	Site ID (preferred over auto-resolve)
`SERVER_PORT`	HTTP server port (default `8080`)

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).

Workspace MCP Server