Glossary & Final Principles

Glossary terms

MCP

Model Context Protocol — a standard way for AI clients to discover and call tools.Instead of teaching a model to call a random API, an MCP server describes its tools in a standard shape. A client can ask 'what tools do you expose?', 'what parameters does each take?', and 'call this tool with these arguments.'

FastMCP

The Python SDK helper used to build MCP servers quickly.FastMCP (from the Python MCP SDK) handles the MCP protocol details so you focus on writing tools as plain async functions.

Streamable HTTP

The MCP transport that uses HTTP requests to a single server endpoint.The server exposes one HTTP endpoint, /mcp, and the MCP client sends JSON-RPC-style requests through it. The reference server uses stateless_http=True and json_response=True so it works cleanly behind gateways and load balancers.

Tool

A callable function exposed by the MCP server for an AI client to call.A tool's name, typed arguments, and docstring are all part of what the MCP client discovers. Good tools do one clear thing and return a small, predictable object.

Copilot Studio

Microsoft platform for building agents and connecting tools.Copilot Studio consumes the MCP server through a Power Platform custom connector and lets users chat with an agent that calls your tools.

Power Platform custom connector

The connector layer Copilot Studio uses to call external services.For MCP, the connector exposes a single /mcp POST operation and must carry the x-ms-agentic-protocol extension so Copilot Studio treats it as an MCP tool source.

x-ms-agentic-protocol

The connector extension that marks a connector as an agentic MCP connector.The critical line is "x-ms-agentic-protocol": "mcp-streamable-1.0". Without it, Copilot Studio may treat the connector like a normal REST API instead of an MCP endpoint.

OAuth 2.0 3LO

Three-legged OAuth, where the user grants delegated access.The three legs are the user, the client application (the Power Platform/Copilot Studio connector), and the resource provider (Atlassian). The user signs in and the server receives a short-lived access token for that user.

Delegated token

An access token representing the signed-in user.The MCP server forwards the user's delegated token to Jira, so Jira enforces that user's permissions. The server never owns a Jira identity.

PAT

Personal access token — a standing credential, avoided here for Jira access.PATs and service accounts are shared standing credentials. This design avoids them in favor of per-request delegated tokens.

APIM

Azure API Management — the public gateway in front of the MCP server.APIM provides the HTTPS endpoint, CORS, IP filtering, rate limits, quotas, header checks, and injects the gateway integrity secret. The app still validates security itself; APIM is not the only line of defense.

Key Vault

Azure service for storing secrets securely.Key Vault stores the gateway shared secret. APIM reads it as a named value and the app verifies it, proving a request came through APIM.

Application Insights

Azure telemetry service for logs and traces.When APPLICATIONINSIGHTS_CONNECTION_STRING is set, the app exports logs and traces to Azure Monitor. Tokens and secrets are redacted before logging.

ACR

Azure Container Registry — stores the built container image.The deploy script builds the image in ACR, so you do not need local Docker to deploy.

App Service

Azure web app hosting service.A familiar web-app hosting model with built-in health checks. One of two supported hosting options (the other is Container Apps).

Container Apps

Azure container-native application hosting service.Offers container-native scaling, revisions, and HTTP-concurrency scaling. The other supported hosting option.

Bicep

Azure infrastructure-as-code language.The reference implementation defines all Azure resources in Bicep files under infra/, so deployments are repeatable.

JQL

Jira Query Language — the search syntax for Jira issues.The jira_search tool accepts JQL such as 'assignee = currentUser() AND statusCategory != Done'.

cloudId

Atlassian identifier for a specific Jira Cloud site.Atlassian's Jira Cloud API uses the cloudId in the URL: https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3. The server resolves it from the user's accessible resources.

ADF

Atlassian Document Format, required for rich-text fields in Jira REST v3.Comments and descriptions must be sent as ADF, not plain strings. A small helper, text_to_adf, wraps plain text into a minimal ADF document.

Payload trimming

Reducing responses to safe, compact shapes before returning them to the agent.Agent platforms have response-size limits. Trimming requests only needed fields, converts to small models, clips long text, and enforces a byte budget to avoid AsyncResponsePayloadTooLarge.

Byte budget

The maximum serialized response size the server will return.Controlled by MAX_RESPONSE_BYTES (default 90000). If a result is too big, the trimmer clips summaries, then drops trailing issues, and reports how many were omitted.

Smoke test

A small end-to-end test that verifies essential behavior after startup or deploy.scripts/smoke.py checks /healthz, that /mcp without a bearer returns 401, and that MCP initialize works with a bearer token.

ContextVar

A Python construct that isolates per-request state across concurrent async requests.The user's bearer token is stored in a ContextVar so concurrent requests from different users never overlap. Middleware sets it per request and resets it in a finally block.

Gateway shared secret

A secret APIM injects (X-Gateway-Token) so the app can prove a request came through APIM.Stored in Key Vault, injected by APIM, and verified by the app. This blocks direct access to the app host that bypasses the gateway.

Final implementation principles

1. 1Start native MCP-first.
2. 2Keep /mcp as the primary agent endpoint.
3. 3Use delegated identity whenever user data is involved.
4. 4Do not store user tokens in the MCP server.
5. 5Put APIM in front for production.
6. 6Use Key Vault for gateway secrets.
7. 7Validate the gateway secret in the app, not only in APIM.
8. 8Return compact, typed results.
9. 9Cap search sizes.
10. 10Test auth failures as carefully as success paths.
11. 11Treat the connector schema as production code.
12. 12Prefer clear, narrow tools over broad API passthrough tools.
13. 13Make local development easy, but do not weaken production security.
14. 14Document every required portal value, redirect URI, scope, and environment variable.
15. 15Validate the whole path: Copilot Studio → connector → APIM → MCP server → upstream and back.