add API calls

Author: ranbel

src/content/docs/cloudflare-one/applications/configure-apps/mcp-servers/linked-apps.mdx

@@ -6,9 +6,9 @@ sidebar:
   label: Enable MCP OAuth to self-hosted apps
 ---
 
-import { Render, GlossaryTooltip } from "~/components"
+import { Render, GlossaryTooltip, APIRequest } from "~/components"
 
-Cloudflare Access can delegate access from any [self-hosted application](/cloudflare-one/applications/configure-apps/self-hosted-public-app/) to an [Access for SaaS MCP server](/cloudflare-one/applications/configure-apps/mcp-servers/saas-mcp/) via [OAuth](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization). The OAuth grant authorizes the MCP server to make requests to your self-hosted applications on behalf of the user, using the user's specific permissions and scopes.
+Cloudflare Access can delegate access from any [self-hosted application](/cloudflare-one/applications/configure-apps/self-hosted-public-app/) to an [Access for SaaS MCP server](/cloudflare-one/applications/configure-apps/mcp-servers/saas-mcp/) via [OAuth](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization). The OAuth access token authorizes the MCP server to make requests to your self-hosted applications on behalf of the user, using the user's specific permissions and scopes.
 
 For example, your organization may wish to deploy an MCP server that helps employees interact with internal Atlassian applications. You can configure [Access policies](/cloudflare-one/policies/access/#selectors) to ensure that only authorized users can access those applications, either directly or by using an <GlossaryTooltip term="MCP client">MCP client</GlossaryTooltip>.
 
@@ -34,13 +34,104 @@ accTitle: Link MCP servers and self-hosted applications in Access
 		idp[Identity provider] <--> SaaS
 ```
 
+This guide covers how to use the Cloudflare API to link a self-hosted application to a remote MCP server. The core of this feature is the `linked_app_token` rule type, which allows an Access policy on one application to accept OAuth access tokens generated for another.
+
 ## Prerequisites
 
-## 1. Create an Access policy
+- A [self-hosted Access application](/cloudflare-one/applications/configure-apps/self-hosted-public-app/)
+
+## 1. Secure the MCP server with Access for SaaS
+
+The first step is to add the MCP server to Cloudflare Access as an OIDC-based SaaS application. For step-by-step instructions on how to add an MCP server, refer to [Secure MCP servers with Access for SaaS](/cloudflare-one/applications/configure-apps/mcp-servers/saas-mcp/).
+
+## 2. Get the SaaS application ID
+
+Get the `id` of the MCP server SaaS application:
+
+<APIRequest
+  path="/accounts/{account_id}/access/apps"
+  method="GET"
+/>
+
+```json title="Response"
+{
+	"id": "3537a672-e4d8-4d89-aab9-26cb622918a1",
+	"uid": "3537a672-e4d8-4d89-aab9-26cb622918a1",
+	"type": "saas",
+	"name": "mcp-server-cf-access",
+	...
+}
+```
+
+## 3. Create an Access policy
+
+1. Create the following Access policy, replacing the `app_uid` value with the `id` of your SaaS application:
+
+	<APIRequest
+		path="/accounts/{account_id}/access/policies"
+		method="POST"
+		json={{
+			name: "Allow MCP server",
+			decision: "non_identity",
+			include: [
+			{
+				linked_app_token: {
+					app_uid: "3537a672-e4d8-4d89-aab9-26cb622918a1"
+				}
+			}
+			]
+		}}
+	/>
+
+	:::note
+	The `linked_app_token` rule type works best with `non_identity` decisions, similar to service token rules.
+	:::
+
+2. Copy the Access policy `id` returned in the response:
+
+	```json title="Response" {5}
+	{
+			"created_at": "2025-08-06T20:06:23Z",
+			"decision": "non_identity",
+			"exclude": [],
+			"id": "a38ab4d4-336d-4f49-9e97-eff8550c13fa",
+			"include": [
+				{
+					"linked_app_token": {
+						"app_uid": "6cdc3892-f9f1-4813-a5ce-38c2753e1208"
+					}
+				}
+			],
+			"name": "Allow MCP server",
+			...
+	}
+	```
+
+This policy will allow requests if they present a valid OAuth access token that was issued for the specified SaaS application.
+
+## 4. Update the self-hosted application
+
+1. Get your existing self-hosted application configuration:
+
+	<APIRequest
+		path="/accounts/{account_id}/access/apps/{app_id}"
+		method="GET"
+	/>
+
+2. Add the new Access policy to the self-hosted application. To avoid overwriting your existing configuration, the `PUT` request body should contain all fields returned by the previous `GET` request.
+
+	<APIRequest
+		path="/accounts/{account_id}/access/apps/{app_id}"
+		method="PUT"
+		json={{
+			policies: [
+				"a38ab4d4-336d-4f49-9e97-eff8550c13fa"
+			],
+		}}
+	/>
 
-## 2. Update the self-hosted app
+## 5. Configure the MCP server
 
-## 3. Configure the MCP server
 
 ## Known limitations