Overview

The Port MCP Server implements a Model Context Protocol (MCP) backend designed to give AI agents and developer tools structured, actionable context about your projects and infrastructure. It functions as a centralized context service and tool registry that agents can query to build software catalogs, surface runbooks and docs, and request or execute well-scoped self-service actions (for example, open a PR, run a test suite, or restart a service).

By exposing a small set of APIs and connectors, the server makes it straightforward to integrate AI assistants into developer portals, CI systems, and IDEs. Agents use MCP to ask for relevant context (repository metadata, recent deploys, open incidents) and to call pre-authorized tools that perform safe, auditable actions—reducing manual friction while keeping control and observability in your stack.

Repository: https://github.com/port-labs/port-mcp-server

Features

Exposes a Model Context Protocol (MCP) API for agents to request structured context
Catalog generation: index repositories, services, and metadata for quick discovery
Action registry: define self-service, policy-gated actions agents can invoke
Connectors for common sources (VCS, CI/CD, observability, docs) to enrich context
Authentication and authorization hooks (API keys, JWTs, or platform SSO)
WebSocket and REST interfaces for low-latency IDE integration
Audit logs and event hooks to record agent actions and approvals
Docker-friendly and configurable via environment variables

Installation / Configuration

Minimum steps to run locally. Adjust env variables for your environment and connectors.

Clone and install

git clone https://github.com/port-labs/port-mcp-server.git
cd port-mcp-server
# If Node.js based
npm install
# or
yarn install

Example environment (.env)

PORT=8080
NODE_ENV=development

# Storage and auth
DATABASE_URL=postgres://mcp:mcp@localhost:5432/mcp
JWT_SECRET=replace-with-a-secure-secret

# Optional connectors
GITHUB_TOKEN=ghp_...
OPENAI_API_KEY=sk-...

Run locally

npm run build
npm start
# or for development
npm run dev

Run with Docker Compose (example)

version: "3.8"
services:
  mcp:
    image: port-labs/port-mcp-server:latest
    ports:
      - "8080:8080"
    environment:
      - DATABASE_URL=postgres://mcp:mcp@db:5432/mcp
      - JWT_SECRET=${JWT_SECRET}
  db:
    image: postgres:15
    environment:
      - POSTGRES_USER=mcp
      - POSTGRES_PASSWORD=mcp
      - POSTGRES_DB=mcp

docker compose up -d

Available Resources

The server exposes several primary resource types agents and integrations use:

/api/catalog — list and search indexed projects, services, and packages
/api/context — request aggregated context for a target entity (repo, service, incident)
/api/actions — enumerate and invoke pre-defined self-service actions
/api/auth — token exchange, session management, and SSO callbacks
/ws — optional WebSocket endpoint for push notifications and IDE sessions

Sample curl: fetch context for a repository

curl -H "Authorization: Bearer $MCP_TOKEN" \
  "http://localhost:8080/api/context?target=repo:org/name"

Use Cases

Build a Software Catalog
- Periodically index repositories, package manifests, and deployment metadata.
- Present a searchable catalog in your developer portal so engineers can quickly find code ownership, CI status, and recent deploys.
Self-Service Developer Actions
- Define actions like “create-feature-branch”, “run-smoke-tests”, or “restart-service” with role-based checks.
- Let agents call those actions (via /api/actions) so users can request routine changes without manual ops intervention. Every action is logged and auditable.
IDE Integration (VS Code / JetBrains)
- Use the WebSocket endpoint to stream selective context into the IDE: file-level metadata, test coverage, or known security findings.
- Agents can offer inline suggestions and one-click actions (open PR, run tests) from the editor context.
Incident Triage and Runbooks
- Aggregate observability signals and link to runbooks in the catalog.
- When an alert is raised, agents can fetch the most relevant runbook and execute approved mitigation steps.

Getting Started Tips

Start by setting up a single connector (e.g., GitHub) and index a few repos to validate the catalog.
Define one or two safe actions and test the end-to-end flow: agent requests context → user approves action → server executes and logs the result.
Integrate with your IDE using the WebSocket endpoint for low-latency improvements to developer workflows.
Use environment variables and secrets management for tokens; enable audit logs before enabling destructive actions.

For full source, examples and configuration details, see the project repository: https://github.com/port-labs/port-mcp-server

Port MCP Server: Developer Portal AI Integration