MCP Gateway — How It Works

Developer

Connection Flow

When you connect an AI tool (Claude Code, Cursor, etc.) to the MCP Gateway, the following happens:

Authentication — your API Token is validated and your organization, product, and role are identified.
Instructions loading — the Gateway loads the customizable instructions configured for your MCP Server.
Tool listing — the Gateway returns all available tools (platform + integration tools).

Tool Types

The MCP Gateway exposes two types of tools:

Type	Source	Availability	Examples
Core Tools	Built into Prodgy	Always available for every product	Project context, knowledge search, agent execution, integration management, MCP settings
Integration Tools	Generated from installed integrations	Varies per organization — depends on which integrations are active	Work item management, pull requests, CRM operations, messaging

Core Tools provide access to Prodgy’s own capabilities — the knowledge base, AI agents, integration catalog, and platform configuration. They exist regardless of which external services your organization uses.

Integration Tools are generated dynamically from your organization’s active integrations. Each integration you install (Azure DevOps, Jira, Slack, HubSpot, etc.) automatically adds its own tools to the Gateway. The more integrations you activate, the more tools become available — without any code changes.

Tool Discovery

When the AI client requests the list of available tools, the Gateway combines both types into a single list.

For integration tools, a disambiguation mechanism handles conflicts:

Tools are grouped by their generic name (e.g., create_work_item).
If only one integration provides a given tool name, it’s registered as-is.
If multiple integrations provide the same name, an _integration parameter is added so the AI can choose which one to use.

Tool Execution

When you (or the AI client) call a tool:

Platform Tools

The Gateway handles the request and delegates to the Prodgy API. For example:

search_knowledge performs a semantic search on your workspace’s knowledge base
invoke_agent triggers a Prodgy AI agent with its own tools and system prompt

Integration Tools

The Gateway routes the request to the appropriate integration:

Identifies which integration provides the tool.
If multiple integrations provide the same tool and no _integration was specified, returns a disambiguation message listing the options.
Executes the tool via the Prodgy API, which handles credential resolution and the HTTP call to the external service.

Automatic Boot Context

On the first tool call of each session, the Gateway automatically includes both the user profile (get_my_profile) and the workspace info (get_workspace_info) alongside the tool result. This ensures the AI client always has the authenticated user identity AND your workspace context (vision, OKRs, active integrations) without requiring an explicit call.

Access Control

Access to tools is determined by your authentication method and user role:

API Tokens — full access to all tools. Role-based restrictions apply: tools that create, update, or delete platform-level resources (integration templates, MCP settings) require the SUPERADMIN or ADMIN role. Other tools are available to any authenticated user.
OAuth tokens — access is limited by the scopes granted during authorization. Each tool requires a specific scope (mcp:read, mcp:write, mcp:execute, or mcp:admin). Calls without the required scope return a 403 Forbidden error.

Your role is determined by the credentials used to connect. Users without the required role or scope receive a Forbidden error when calling restricted tools.

Next Steps

Overview — transport modes and available tools
How to Use — step-by-step setup for Claude Code, Cursor, Windsurf, and Claude Desktop