MCP-Native Enterprise Integration Hub

Overview

A governed AI agent platform that exposes GitHub Issues, Jira, and Slack as MCP (Model Context Protocol) servers. A LangGraph orchestration agent routes plain-language requests through Pydantic-validated tool schemas with a mandatory HITL approval checkpoint gating all write operations before execution. Every agent decision, tool call, and action outcome is persisted to PostgreSQL for full audit trail, with PGVector semantic search surfacing relevant historical actions before each new action is planned.

Architecture

graph TD
  User -->|POST /agent/run| FastAPI
  FastAPI --> LangGraph
  LangGraph --> ParseIntent
  ParseIntent --> RetrieveSimilar
  RetrieveSimilar -->|PGVector| PostgreSQL
  RetrieveSimilar --> PlanAction
  PlanAction --> HITLGate
  HITLGate -->|Write op| HITLApproval[(PostgreSQL HITLApproval)]
  HITLGate -->|Read op| ExecuteAction
  ExecuteAction --> GitHubMCP
  ExecuteAction --> JiraMCP
  ExecuteAction --> SlackMCP
  ExecuteAction --> LogRun
  LogRun --> PostgreSQL

Required OAuth Scopes

Slack: channels:read, channels:history, chat:write GitHub: repo (for private repos) or public_repo Jira: read:jira-work, write:jira-work

Setup

# 1. Clone and enter the project
git clone <repo-url> mcp-enterprise-hub
cd mcp-enterprise-hub

# 2. Create and activate a virtual environment
python3 -m venv venv
source venv/bin/activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Configure environment variables
cp .env.example .env
# Edit .env and fill in: ANTHROPIC_API_KEY, OPENAI_API_KEY, GITHUB_TOKEN,
# JIRA_API_TOKEN, JIRA_EMAIL, JIRA_BASE_URL, SLACK_BOT_TOKEN

# 5. Start PostgreSQL (with pgvector)
docker compose up -d postgres

# 6. Initialize the database schema
python src/db/init_db.py

# 7. Run the API server
uvicorn src.api.main:app --reload

# 8. (Optional) Run the test suite
docker compose up -d postgres   # test DB is created automatically on first run
pytest --cov=src --cov-report=term-missing tests/

Port conflict note: if you already have a local Postgres instance running on port 5432 (common on macOS via Homebrew or Postgres.app), Docker's port mapping can silently lose the race for that port — docker compose up -d will report the container as healthy, but localhost:5432 will actually route to your native Postgres instead, which doesn't have the mcp_enterprise_hub role/database and will fail with FATAL: role "postgres" does not exist or similar. Either stop the local Postgres service, or remap the container to a free port with a docker-compose.override.yml:

services:
  postgres:
    ports:
      - "5433:5432"

and update DATABASE_URL / TEST_DATABASE_URL in .env to use port 5433.

Example API Calls

1. Read operation (list GitHub issues) — completes immediately:

curl -X POST http://localhost:8000/agent/run \
  -H "Content-Type: application/json" \
  -d '{"message": "list open issues in octo/hello"}'

{
  "status": "completed",
  "result": {
    "issues": [
      {"id": 1, "number": 42, "title": "Login button unresponsive", "state": "open", "url": "https://github.com/octo/hello/issues/42"}
    ],
    "metadata": {"is_write": false, "connector": "github", "tool_name": "list_issues"}
  },
  "run_id": "6a9b1a2e-4c9b-4c1e-9c0e-7a1f2b3c4d5e",
  "session_id": "d1e2f3a4-5b6c-7d8e-9f0a-1b2c3d4e5f6a"
}

2. Write operation (create a Jira ticket) — returns pending_approval:

curl -X POST http://localhost:8000/agent/run \
  -H "Content-Type: application/json" \
  -d '{"message": "create a Jira ticket in project ABC titled '\''Login button unresponsive on mobile'\''"}'

{
  "status": "pending_approval",
  "approval_id": "9f8e7d6c-5b4a-3c2d-1e0f-a1b2c3d4e5f6",
  "action_plan": {
    "connector": "jira",
    "tool_name": "create_issue",
    "validated_params": {
      "project_key": "ABC",
      "summary": "Login button unresponsive on mobile",
      "description": "Login button unresponsive on mobile",
      "issue_type": "Bug"
    },
    "is_write_operation": true,
    "risk_level": "medium"
  },
  "session_id": "d1e2f3a4-5b6c-7d8e-9f0a-1b2c3d4e5f6a"
}

3. Approve the write — executes and returns the result:

curl -X POST http://localhost:8000/agent/approve/9f8e7d6c-5b4a-3c2d-1e0f-a1b2c3d4e5f6 \
  -H "Content-Type: application/json" \
  -d '{"reviewer_notes": "Looks good, approved"}'

{
  "status": "approved",
  "result": {
    "key": "ABC-123",
    "url": "https://your-domain.atlassian.net/browse/ABC-123",
    "metadata": {"is_write": true, "connector": "jira", "tool_name": "create_issue"}
  },
  "run_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
}

Test Results

$ pytest --cov=src --cov-report=term-missing tests/

collected 52 items

tests/test_agent.py .............                                        [ 25%]
tests/test_api.py ..................                                     [ 59%]
tests/test_mcp_servers.py .....................                          [100%]

================================ tests coverage ================================
Name                               Stmts   Miss  Cover   Missing
----------------------------------------------------------------
src/__init__.py                        0      0   100%
src/agent/__init__.py                  0      0   100%
src/agent/hitl.py                     29      1    97%   33
src/agent/state.py                    13      0   100%
src/agent/workflow.py                189      5    97%   108, 263-266
src/api/__init__.py                    0      0   100%
src/api/main.py                      209      3    99%   150-152
src/db/__init__.py                     0      0   100%
src/db/database.py                    16      0   100%
src/db/init_db.py                     16     16     0%   1-24
src/db/models.py                      60      0   100%
src/db/vector_search.py                7      0   100%
src/mcp_servers/__init__.py            0      0   100%
src/mcp_servers/common.py             11      0   100%
src/mcp_servers/github_server.py      95      3    97%   7, 175-177
src/mcp_servers/jira_server.py        81      3    96%   7, 168-170
src/mcp_servers/slack_server.py       86      4    95%   7, 144, 161-163
----------------------------------------------------------------
TOTAL                                812     35    96%

52 passed in 2.92s

HITL block rate (measured against the persisted test database after a full suite run, before per-test truncation):

Metric	Count
Write-intent runs that reached hitl_gate	9
Runs where hitl_gate correctly created a HITLApproval record	9 / 9 (100%)
Real MCP tool executions recorded in AuditLog	4
Of those, executed without a prior APPROVED approval	0
Writes rejected and never executed	2

Every write-operation test run was intercepted by the HITL gate before any MCP tool call could fire; no execution reached AuditLog without a matching APPROVED HITLApproval row.

Resume Metrics (for reference)

• 19 agent runs persisted to PostgreSQL during testing
• 85%+ test coverage across MCP servers, agent, and API layers
• HITL gated 100% of write operations in test suite (0 unreviewed writes executed)