Chapter 1 · Understand

Core Concepts

The eight ideas that everything else builds on: MCP and tools, streamable HTTP, native MCP versus REST, delegated OAuth 3LO, the Copilot Studio connector, APIM, Key Vault, and payload trimming.

🎯 What you'll be able to do

Define MCP, tools, and streamable HTTP
Explain why native MCP is preferred over a REST fallback
Describe delegated OAuth 2.0 3LO and why no service account is used
Say what APIM, Key Vault, and payload trimming each protect against

What is MCP?

Model Context Protocol is a protocol for connecting AI applications to tools and data sources. Instead of teaching the model to call a random API directly, an MCP server describes tools in a standard way. A client can ask:

What tools do you expose?
What parameters does each tool accept?
Call this tool with these arguments.

In the reference implementation, FastMCP from the Python MCP SDK handles the protocol details for you.

Tools

A tool is a callable function exposed to the agent. Its name, typed arguments, and docstring are all part of what the MCP client discovers. The reference server exposes tools like these:

Tool	Purpose
`jira_whoami`	Return the signed-in Jira user.
`jira_search`	Search Jira with JQL.
`jira_get_issue`	Return one trimmed issue.
`jira_create_issue`	Create an issue.
`jira_add_comment`	Add a comment.
`jira_transition_issue`	Apply a workflow transition.
`jira_get_projects`	List visible projects.

The golden rule of tool design

A tool should do one clear thing and return a predictable, compact object. You'll revisit this in Build Your Own.

Streamable HTTP

Streamable HTTP is the MCP transport used here. The server exposes one HTTP endpoint, /mcp, and the client sends JSON-RPC-style requests through it. The reference server creates the app like this:

Python

FastMCP(settings.server_name, stateless_http=True, json_response=True)

Setting	Meaning
`stateless_http=True`	Every request is self-contained — important behind gateways and cloud load balancers.
`json_response=True`	Return buffered JSON instead of relying on a long-lived streaming connection. Gateway-friendly.

Native MCP versus REST fallback

Native MCP exposes a single /mcp operation and the agent discovers tools dynamically. A REST fallback exposes separate operations like /tools/jira_search — easier to grasp at first, but it loses dynamic discovery and forces you to maintain connector operations by hand.

✓ Native MCP (primary design)

One /mcp operation; tools discovered dynamically
Copilot Studio treats it as an MCP tool source
New tools appear automatically

✗ REST fallback (last resort)

One REST route per tool, maintained manually
Behaves like an ordinary REST connector
Every new tool means new connector work

Don't 'simplify' to REST

REST can feel familiar, so it's tempting. The build review was explicit: native MCP is the correct primary design. Keep REST only for environments that genuinely cannot use MCP — never convert the production design to REST just because it feels easier.

The Copilot Studio MCP connector

Copilot Studio consumes the server through a Power Platform custom connector. The important file is openapi\\mcp-connector.swagger.json, and the critical line is:

JSON

"x-ms-agentic-protocol": "mcp-streamable-1.0"

Warning

Without that extension, Copilot Studio may treat the connector like a normal REST connector instead of an MCP tool source — and no tools will appear.

Delegated OAuth 2.0 3LO

Delegated OAuth means the user signs in and grants access; the server receives a short-lived access token for that user. 3LO means three-legged OAuth, with three parties:

1. User

The person asking the agent a question.

2. Client app

The Power Platform / Copilot Studio connector.

3. Resource provider

Atlassian, which owns the Jira data.

The server does not own a Jira identity. It forwards the user's token to Jira, so permissions stay correct automatically:

If the user can see an issue, the tool can see it.
If the user cannot, Jira rejects the request.
The server never recreates Jira's permission logic.

No service account. No PAT.

This design deliberately avoids shared standing credentials. They over-grant access, are hard to rotate, and turn one leak into a tenant-wide incident. Delegated per-user tokens are the safe default.

Azure API Management (APIM)

Azure API Management is the public gateway in front of the MCP server. It provides:

An HTTPS gateway endpoint
CORS policy and IP filtering
Rate limits and quotas
Header checks and gateway integrity secret injection
Response hardening headers

Note

APIM is not the only line of defense. The app still validates its security assumptions — defense in depth.

Azure Key Vault

Key Vault stores the gateway shared secret. APIM reads it as a named value and injects it as X-Gateway-Token; the app verifies it. That secret proves a request actually came through APIM, blocking attempts to reach the app host directly.

Payload trimming

Agent platforms have response-size limits. Jira issue payloads can be huge (descriptions, comments, changelogs, custom fields). The reference implementation prevents oversized responses by:

Requesting only the fields it needs from Jira.
Converting issues into small response models.
Clipping long text.
Enforcing a byte budget before returning data to Copilot Studio.

❓ Concept check

A teammate suggests returning the full raw Jira JSON “so the agent has everything.” Why is that a bad idea here?

▶ Watch to reinforce this conceptOptional supplement

📌 Chapter summary

MCP standardises how an agent discovers and calls tools.
Streamable HTTP exposes one /mcp endpoint; stateless_http and json_response make it gateway-friendly.
Native MCP is the primary design; REST is only a fallback for environments that can't use MCP.
Delegated 3LO runs actions as the user — no service accounts, no PATs. APIM, Key Vault, and trimming protect the edge, secrets, and response size.

✅ End-of-chapter review

0/5 done

I can define MCP and a tool
I know why stateless_http and json_response matter
I can argue for native MCP over REST
I can explain delegated 3LO and why no service account
I know what APIM, Key Vault, and trimming protect