MCP Settings

Developer

What are MCP Settings?

The MCP Settings control how the MCP Gateway behaves — specifically the instructions (system prompt) sent to AI clients and the rules for creating integration templates.

Available Tools

Tool	Description
`get_mcp_settings`	View the current MCP Server configuration
`update_mcp_settings`	Update the instructions and rules

Instructions

The instructions field defines how AI clients should behave when connected to the MCP Gateway. For example:

Always call get_my_profile first, then get_workspace_info
How to handle integration errors
Rules for creating integration templates
Formatting preferences for work items

You can also manage instructions through the Prodgy UI: Settings > MCP Server.

Initialization flow

The two first tools any MCP session must call, in order, are:

get_my_profile — loads the authenticated user identity (full_name, email, role, position, language), the user’s organization (name, info, industry, size, stage, etc.) and ai_preferences (the user’s personal markdown directive and a destructive-action confirmation flag). Available only in authenticated user sessions.
get_workspace_info — loads the workspace/product context (vision, target audience, personas, value proposition, active integrations).

If the AI client skips these calls, the gateway auto-injects both on the first CallTool it receives. Service-to-service callers (e.g. the agentic runtime backing the playground) can opt into the user-scoped flow by forwarding the X-Prodgy-User-Id header — when present, get_my_profile resolves the real on-behalf user. Without it, get_my_profile returns unauthenticated_context and only get_workspace_info is auto-injected.

`get_my_profile` — example payload

{
  "user": {
    "id": "uuid",
    "full_name": "Santhiago Silva",
    "email": "santhiago.silva@programmers.com.br",
    "role": "superadmin",
    "position": "Senior Product Manager",
    "language": "pt-BR"
  },
  "organization": {
    "id": "uuid",
    "name": "Programmers",
    "info": "Software house with 100+ engineers focused on enterprise platforms.",
    "industry": "Software",
    "size": "medium",
    "stage": "established",
    "website": "https://programmers.com.br",
    "logo_url": "https://..."
  },
  "ai_preferences": {
    "instructions": "Always reply in pt-BR. Always show a TL;DR at the end.",
    "instructions_format": "markdown",
    "confirm_destructive_actions": true
  },
  "_instructions": "You now have the user identity, organization metadata and personal AI preferences. Next, call get_workspace_info..."
}

The user’s workspaces/products are intentionally NOT included here — get_workspace_info is the source of truth for the current workspace.

Edge cases handled by the gateway:

Scenario	Response
Unsupported `language` (not in `pt-BR`, `en-US`, `es-ES`)	`language: ""`
Profile not linked to any organization	`organization: null`
Profile missing `email`/`full_name`	`{ error: "incomplete_profile", missing_fields: [...] }`
Service-to-service or missing `userId`	`{ error: "unauthenticated_context" }`

`update_my_ai_preferences`

Lets the AI client persist the user’s preferences on demand. Accepts instructions (markdown text) and/or confirm_destructive_actions (boolean) — at least one must be provided.

// Input
{ "instructions": "Always reply in pt-BR.", "confirm_destructive_actions": true }

// Output
{
  "user_id": "uuid",
  "ai_preferences": {
    "instructions": "Always reply in pt-BR.",
    "instructions_format": "markdown",
    "confirm_destructive_actions": true
  },
  "_message": "Your AI preferences were updated. They will apply on the next get_my_profile call."
}

When the LLM should invoke this tool:

Persisting a rule the user explicitly asks for (“always do X”, “never do Y”, “stop asking me before deletes”, “save this as my preference”).
Suggesting a rule after spotting the same prescriptive pattern repeated 3+ times in the session — always ask for confirmation before calling the tool.

When NOT to invoke:

Proactively, without an explicit user request.
To store descriptive facts about the user (team, projects, history). Those will be handled by a future memories tool, not preferences.

Edge cases:

Empty string in instructions clears the markdown directive.
Service-to-service or missing userId → { error: "unauthenticated_context" }.
No fields provided → { error: "validation_error" }.

Updating instructions

"Update the MCP settings instructions to always include the sprint number when creating work items"

Export Rules

The exports field contains rules and examples for creating integration templates. This is what guides the AI when create_integration is called — ensuring templates follow the correct structure with proper placeholders, authentication patterns, and tool definitions.