SEI MCP Server (TypeScript)

SEI MCP Server for Gemini Enterprise

A production-ready Model Context Protocol (MCP) server built with Node.js, Express, and TypeScript providing full integration with the SEI (Sistema Eletrônico de Informações) APIs of the São Paulo State Government (IntegradorSP / Rota.SP).

Equipped with dual transports (StreamableHTTP on /mcp and SSE on /sse), Google OAuth 2.0 discovery endpoints, automated IDP.SP token management, and comprehensive tools for Gemini Enterprise, Claude, and MCP clients.

🏛️ Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                           Gemini Enterprise                             │
│                  (Admin Console / Extensions / Tools)                   │
└────────────────────────────────────┬────────────────────────────────────┘
                                     │
                 HTTPS / SSE Request with Google OAuth Bearer Token
                 `Authorization: Bearer <OAUTH_ACCESS_TOKEN>`
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                 GCP External Application Load Balancer                  │
│                (Global Static IP + Managed SSL via Terraform)           │
└────────────────────────────────────┬────────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                   Serverless NEG / Google Cloud Run                     │
│                        (Container on Port 3000)                         │
└────────────────────────────────────┬────────────────────────────────────┘
                                     │
        ┌────────────────────────────┼────────────────────────────┐
        │                            │                            │
        ▼                            ▼                            ▼
┌───────────────────────┐  ┌─────────────────────┐  ┌─────────────────────┐
│      GET /health      │  │      POST /mcp      │  │     GET /sse &      │
│(Unauthenticated Probe)│  │  (StreamableHTTP)   │  │   POST /messages    │
└───────────────────────┘  └──────────┬──────────┘  └──────────┬──────────┘
                                      │                        │
                                      ▼                        ▼
                       ┌──────────────────────────────────────────────┐
                       │                SEI Client                    │
                       │ (IDP.SP OAuth Auth Gate + Request Headers)   │
                       └──────┬───────────────┬──────────────┬────────┘
                              │               │              │
                              ▼               ▼              ▼
                   ┌──────────────────┐ ┌───────────┐ ┌───────────────┐
                   │  sei-processos   │ │sei-docum. │ │sei-parametros │
                   │(Gestão Processos)│ │(Documentos│ │(Unidades,     │
                   │                  │ │ e Anexos) │ │Contatos,etc.) │
                   └──────────────────┘ └───────────┘ └───────────────┘

📋 Prerequisites

• Google Cloud SDK (gcloud) installed and authenticated.
• Terraform CLI  (>= 1.5.0).
• Node.js  (v20.x or v22.x LTS) & npm (for local development).
• A Google Cloud Project with billing enabled and the following APIs activated:

  gcloud services enable run.googleapis.com compute.googleapis.com cloudbuild.googleapis.com

• SEI Credentials (IDP.SP client credentials / token, SiglaSistema, Identificação de Serviço, ID Unidade).

⚙️ Configuration & Environment Variables

Configure server behavior and SEI integration parameters in .env (refer to .env.example):

Server & Security Settings

SEI APIs & IDP.SP Authentication

🚀 Streamlined Deployment: Gemini Enterprise with Terraform

Follow these step-by-step instructions to deploy the SEI MCP server to Google Cloud and connect it to Gemini Enterprise.

Step 1: Build & Deploy Container to Cloud Run

Build the multi-stage Docker image using Google Cloud Build and deploy it to Google Cloud Run:

# 1. Ensure you are in the project root directory
cd /path/to/sei-mcp
 
# 2. Set your GCP project
gcloud config set project YOUR_GCP_PROJECT_ID
 
# 3. Build Docker container image via Cloud Build
gcloud builds submit --tag gcr.io/YOUR_GCP_PROJECT_ID/sei-mcp-server:latest .
 
# 4. Deploy to Cloud Run (Google OAuth 2.0 authentication enforced in production)
gcloud run deploy sei-mcp-server \
  --image gcr.io/YOUR_GCP_PROJECT_ID/sei-mcp-server:latest \
  --region southamerica-east1 \
  --platform managed \
  --allow-unauthenticated \
  --port 3000 \
  --set-env-vars NODE_ENV=production,OAUTH_CLIENT_ID="YOUR_OAUTH_CLIENT_ID.apps.googleusercontent.com",SEI_SIGLA_SISTEMA="INTEGRACAOCLIENTES",SEI_IDENTIFICACAO_SERVICO="YOUR_SEI_TOKEN",SEI_ID_UNIDADE="110000384",IDPSP_CLIENT_ID="YOUR_IDPSP_ID",IDPSP_CLIENT_SECRET="YOUR_IDPSP_SECRET" \
  --min-instances 0 \
  --max-instances 5 \
  --timeout 300

Step 2: Provision Load Balancer & Static IP with Terraform

Use the included Terraform module in infra/ to provision an External Application Load Balancer with a Serverless NEG pointing to your Cloud Run service.

1. Navigate to the infrastructure directory:

   cd infra

2. Create your terraform.tfvars:

   cp terraform.tfvars.example terraform.tfvars

3. Edit infra/terraform.tfvars:

   project_id             = "YOUR_GCP_PROJECT_ID"
   region                 = "southamerica-east1"
   cloud_run_service_name = "sei-mcp-server"
    
   # Optional: Set to true if you have a custom domain pointing to the Load Balancer IP
   enable_ssl  = false
   domain_name = ""

4. Initialize and apply Terraform:

   terraform init
   terraform apply

5. Retrieve the outputs:

   • load_balancer_ip: Static IP of the Load Balancer (e.g. 34.120.x.x).
   • mcp_sse_endpoint_http: SSE endpoint URL (e.g. http://34.120.x.x/sse or https://<YOUR-DOMAIN>/sse).
   • mcp_http_endpoint: StreamableHTTP endpoint URL (e.g. https://<YOUR-DOMAIN>/mcp).

Step 3: Configure Google OAuth 2.0 Credentials in GCP Console

When integrating with Gemini Enterprise, configure the OAuth 2.0 client credentials:

1. Open Google Cloud Console > APIs & Services > Credentials.
2. Click Create Credentials > OAuth client ID.
3. Select Application type: Web application.
4. Set Name: Gemini Enterprise SEI MCP Extension.
5. Under Authorized redirect URIs, add both of the following redirect URIs:
   • https://vertexaisearch.cloud.google.com/oauth-redirect
   • https://vertexaisearch.cloud.google.com/static/oauth/oauth.html
6. Click Create and copy your Client ID and Client Secret.

Step 4: Register Extension in Gemini Enterprise

In the Gemini Enterprise Admin Console (or Vertex AI Extensions / Custom Tools), add a new MCP Server extension using the following values:

Click Validate & Save. Gemini Enterprise connects to the endpoint, performs protocol handshake and tool discovery, and registers all 68+ SEI tools automatically.

Step 5: Verify in Gemini Enterprise Chat

Once registered, users can invoke the SEI tools naturally from Gemini Enterprise prompts:

• “Liste os processos abertos na minha unidade no SEI” → invokes sei_listar_processos
• “Consulte o andamento do processo 03.110000147.0000001/2024-99” → invokes sei_consultar_processo
• “Crie um novo processo administrativo de Compras e Serviços” → invokes sei_gerar_processo
• “Inclua um parecer em HTML no processo” → invokes sei_incluir_documento
• “Quais são as séries documentais disponíveis?” → invokes sei_listar_series
• “Qual o status de saúde do servidor MCP?” → invokes get_system_info

🛠️ Complete MCP Tools Catalog

The server exports all operations from the SEI API documentation across three domains:

1. Processos (sei-processos)

2. Documentos (sei-documentos)

3. Parâmetros e Utilitários (sei-parametros)

💻 Local Development & Testing

1. Install & Run Locally

# Install dependencies
npm install
 
# Run with hot-reload
npm run dev

2. Verify Endpoints with curl

• Health Check:

  curl -i http://localhost:3000/health

• SSE Stream with Google OAuth Access Token:

  curl -N -i -H "Authorization: Bearer $(gcloud auth print-access-token)" http://localhost:3000/sse

• Testing with Authentication Disabled (Local Only):

  OAUTH_ENABLED=false npm run dev
  curl -N -i http://localhost:3000/sse

🔍 Troubleshooting

• 401 Unauthorized / 403 Forbidden:
  • 401 Unauthorized: Missing Authorization: Bearer <token> header in the request.
  • 403 Forbidden: The OAuth 2.0 token is invalid, expired, or failed audience verification against OAUTH_CLIENT_ID. Verify that the OAuth client credentials in Gemini Enterprise match the GCP project settings.
• Connection Timeout: Ensure the Cloud Run service --timeout is set to 300 seconds or higher to support long-lived Server-Sent Events connections.
• Health Check Endpoint: Load balancers and cloud probes can monitor /health (unauthenticated, returns HTTP 200 OK).

📄 License

This project is licensed under the MIT License .