Encrypt MCP OAuth Tokens

Outcome: You can encrypt OAuth tokens so clients only see token ciphertexts instead of plaintext Bearer tokens. This example focuses on Notion MCP OAuth, but this approach should extend to any OAuth DCR flow.
Prerequisites: The Formal Endpoint transparent proxy on macOS. Use Secure Enclave encryption on the Endpoint, or forward traffic to a with token encryption.

Overview

Notion MCP (https://mcp.notion.com/mcp) issues OAuth tokens from the same host (POST /token). Clients then send Authorization: Bearer <token> on MCP calls. Formal can encrypt those tokens in two places:

Where encryption runs	Key material	When to use
Formal Endpoint	macOS Secure Enclave	Encrypt on the device; no traffic through Connector
Connector	Cloud KMS KEK	Encrypt off the device; route MCP traffic through Connector

In both cases:

An encrypt encrypts access_token and refresh_token on the OAuth token response.
The MCP client stores formalsealed:v1:....
A decrypt policy decrypts Authorization before Notion MCP sees the request.

The MCP client keeps using https://mcp.notion.com. You do not rewrite the MCP URL.

Policies

These policies apply whether encryption runs on the Endpoint or the Connector.

Encrypt OAuth tokens

Web Console
Terraform

Navigate to Policies
Click Create Policy
Set name to notion-mcp-encrypt-oauth-tokens and add a description
Paste the Rego below into the editor
Click Create Policy to save

package formal.v2

import future.keywords.if

response := {
  "action": "encrypt",
  "targets": [
    {"kind": "json", "name": "access_token"},
    {"kind": "json", "name": "refresh_token"}
  ],
  "reason": "Encrypt Notion OAuth tokens before they leave the Connector"
} if {
  input.resource.hostname == "mcp.notion.com"
  input.http.method == "POST"
  input.http.path == "/token"
}

resource "formal_policy" "notion_mcp_encrypt_oauth_tokens" {
  name        = "notion-mcp-encrypt-oauth-tokens"
  description = "Encrypt Notion MCP OAuth tokens on the token response"
  status      = "active"

  module = <<-EOT
    package formal.v2

    import future.keywords.if

    response := {
      "action": "encrypt",
      "targets": [
        {"kind": "json", "name": "access_token"},
        {"kind": "json", "name": "refresh_token"}
      ],
      "reason": "Encrypt Notion OAuth tokens before they leave the Connector"
    } if {
      input.resource.hostname == "mcp.notion.com"
      input.http.method == "POST"
      input.http.path == "/token"
    }
  EOT
}

Decrypt Authorization on MCP requests

Web Console
Terraform

Navigate to Policies
Click Create Policy
Set name to notion-mcp-decrypt-authorization and add a description
Paste the Rego below into the editor
Click Create Policy to save

package formal.v2

import future.keywords.if

request := {
  "action": "decrypt",
  "targets": [
    {"kind": "header", "name": "Authorization"}
  ],
  "reason": "Decrypt Notion tokens for the upstream MCP server"
} if {
  input.resource.hostname == "mcp.notion.com"
}

resource "formal_policy" "notion_mcp_decrypt_authorization" {
  name        = "notion-mcp-decrypt-authorization"
  description = "Decrypt Notion tokens on MCP Authorization headers"
  status      = "active"

  module = <<-EOT
    package formal.v2

    import future.keywords.if

    request := {
      "action": "decrypt",
      "targets": [
        {"kind": "header", "name": "Authorization"}
      ],
      "reason": "Decrypt Notion tokens for the upstream MCP server"
    } if {
      input.resource.hostname == "mcp.notion.com"
    }
  EOT
}

Decrypt supports embedded encrypted tokens, so Bearer formalsealed:v1:... becomes Bearer <plaintext> for Notion. Values without an encrypted token pass through unchanged.

Encrypt is fail-closed. If encryption fails, Formal blocks the response. If decryption fails, Formal forwards the request unchanged.

Encrypt on the Formal Endpoint (Secure Enclave)

On macOS, the Formal Endpoint can encrypt and decrypt tokens with the device Secure Enclave. Traffic stays on the Endpoint. You do not set Forward to Connector. Create a network rule that matches Notion MCP. No Connector listener or KMS key is required for this path.

Web Console
Terraform

Navigate to Network Rules (or use Network Rules in the Desktop App)
Create a rule named notion-mcp-endpoint
Match hostname mcp.notion.com on the pre-TLS condition
Leave Forward to Connector unset / false
Save the rule

resource "formal_network_rule" "notion_mcp_endpoint" {
  name        = "notion-mcp-endpoint"
  description = "Intercept Notion MCP for Secure Enclave token encryption"
  status      = "active"

  cel_expression = <<-EOT
    {
      "condition": {
        "pre_tls": hostname == "mcp.notion.com",
        "post_tls": true
      },
      "outputs": {}
    }
  EOT
}

Verify:

Enable the transparent proxy: formal transparent-proxy enable
Confirm the network rule is Active
Complete Notion MCP OAuth. Confirm access_token starts with formalsealed:v1:

Endpoint encrypt is macOS-only. See Encrypt & Decrypt.

Encrypt on the Connector

To encrypt tokens on the Connector, forward Notion MCP through a Connector and attach a token encryption key (formal_connector_token_encryption_key). Without that KEK, Connector encrypt fails closed and blocks the OAuth response. Set up the following:

An MCP resource for mcp.notion.com
A Connector listener and listener rule so the resource is reachable
A token encryption key on the Connector (cloud KMS KEK)
A network rule with forward_to_connector set to true

Web Console
Terraform

Create an MCP resource for hostname mcp.notion.com on port 443
On your Connector, add a listener on port 443 and a listener rule that points at that resource
Attach a token encryption key to the Connector
Create a network rule named notion-mcp-connector that matches mcp.notion.com and sets Forward to Connector

resource "formal_resource" "notion_mcp" {
  name       = "notion-mcp"
  technology = "mcp"
  hostname   = "mcp.notion.com"
  port       = 443
}

resource "formal_connector_listener" "notion_mcp_listener" {
  connector_id = formal_connector.example.id
  name         = "notion-mcp-listener"
  port         = 443
}

resource "formal_connector_listener_rule" "notion_mcp" {
  connector_listener_id = formal_connector_listener.notion_mcp_listener.id
  type                  = "resource"
  rule                  = formal_resource.notion_mcp.id
}

resource "formal_connector_token_encryption_key" "example" {
  connector_id = formal_connector.example.id
  key_provider = "aws-kms"
  key_id       = aws_kms_key.formal_token_kek.arn
}

resource "formal_network_rule" "notion_mcp_connector" {
  name        = "notion-mcp-connector"
  description = "Forward Notion MCP to the Connector for token encryption"
  status      = "active"

  cel_expression = <<-EOT
    {
      "condition": {
        "pre_tls": hostname == "mcp.notion.com",
        "post_tls": true
      },
      "outputs": {
        "resource_name": "notion-mcp",
        "forward_to_connector": true
      }
    }
  EOT
}

See Token Encryption for GCP and Azure KEK setup and IAM requirements.

Forward to Connector must be true. Without it, the Endpoint does not send Notion traffic to the Connector for KMS-backed encrypt and decrypt.

Verify:

Notion MCP appears under the Connector’s Reachable Resources
The Connector has a token encryption key configured
The network rule is Active with Forward to Connector
Complete Notion MCP OAuth. Confirm encrypted formalsealed:v1: tokens and successful MCP tool calls

Add Notion MCP and complete OAuth

After policies and routing are in place, add Notion MCP as usual. Formal does not change Dynamic Client Registration (DCR) or the OAuth browser flow.

Add the Notion MCP server at https://mcp.notion.com/mcp. For Claude Code:

claude mcp add -t http notion https://mcp.notion.com/mcp

You can also add it from the Formal console registry or another MCP client config.

Complete DCR and OAuth when the client prompts you.

Network rules keep intercepting mcp.notion.com, so Claude Code still uses the real Notion URL. Encrypted tokens are what the client persists after /token.

Verify end to end

Keep the MCP client pointed at https://mcp.notion.com/mcp.
Finish OAuth through Claude Code (or your MCP client).
Call a Notion MCP tool. The call should succeed.
Confirm encrypt on POST /token and decrypt on later MCP requests in Formal logs.

Inspect encrypted tokens in Claude Code (macOS)

Claude Code stores MCP OAuth credentials in the macOS Keychain. After OAuth completes, read that entry and confirm Notion tokens are encrypted:

security find-generic-password -s "Claude Code-credentials" -w | jq .

Look under the Notion server entry (key shape like notion|<id>). Both accessToken and refreshToken should start with formalsealed:v1::

{
  "mcpOAuth": {
    "notion|<CLIENT_OR_SERVER_ID>": {
      "serverName": "notion",
      "serverUrl": "https://mcp.notion.com/mcp",
      "accessToken": "formalsealed:v1:...",
      "refreshToken": "formalsealed:v1:...",
      "discoveryState": {
        "authorizationServerUrl": "https://mcp.notion.com",
        "resourceMetadataUrl": "https://mcp.notion.com/.well-known/oauth-protected-resource/mcp",
        "oauthMetadataFound": true
      },
      "scope": "default"
    }
  }
}

Verify:

security find-generic-password -s "Claude Code-credentials" -w \
  | jq -r '.. | objects | select(.serverUrl? == "https://mcp.notion.com/mcp") | .accessToken' \
  | head -n 1
# Expected: a value that starts with formalsealed:v1:

If accessToken is a raw Notion token instead of formalsealed:v1:..., encrypt did not run on POST /token (check the network rule, policies, and Connector token encryption key if you use the Connector path).

Keychain entry names can vary by Claude Code version. If the command finds no password, search Keychain Access for Claude credentials or re-run OAuth after confirming the transparent proxy is enabled.

Troubleshooting

Token response is not encrypted

Possible causes:

Transparent proxy or network rule is inactive
Connector path missing forward_to_connector or KEK
Policy path does not match POST /token

Fix:

Run formal transparent-proxy status
Set the network rule to Active
For Connector encryption, confirm the token encryption key, listener rule, and forward_to_connector

MCP calls return 401 Unauthorized

Possible causes:

Encrypt ran, but decrypt did not match mcp.notion.com
Encrypted token came from a different Endpoint or Connector KEK
Client truncated the formalsealed:v1: value

Fix:

Confirm the decrypt policy matches input.resource.hostname == "mcp.notion.com"
Re-authenticate after rotating keys
Keep the full encrypted string in Authorization: Bearer ...

Next Steps

MCP Resources

Proxy and govern MCP traffic

Token Encryption

Configure the Connector KMS KEK

Encrypt & Decrypt

Full action reference

Desktop App

Enable the transparent proxy

Getting Started

Configuring Formal

Leveraging Formal

Integrations

Configuration

Client Apps

Example Use Cases

Overview

Policies

Encrypt OAuth tokens

Decrypt Authorization on MCP requests

Encrypt on the Formal Endpoint (Secure Enclave)

Encrypt on the Connector

Add Notion MCP and complete OAuth

Verify end to end

Inspect encrypted tokens in Claude Code (macOS)

Troubleshooting

Next Steps

MCP Resources

Token Encryption

Encrypt & Decrypt

Desktop App

​Overview

​Policies

​Encrypt OAuth tokens

​Decrypt Authorization on MCP requests

​Encrypt on the Formal Endpoint (Secure Enclave)

​Encrypt on the Connector

​Add Notion MCP and complete OAuth

​Verify end to end

​Inspect encrypted tokens in Claude Code (macOS)

​Troubleshooting

​Next Steps

MCP Resources

Token Encryption

Encrypt & Decrypt

Desktop App

Overview

Policies

Encrypt OAuth tokens

Decrypt Authorization on MCP requests

Encrypt on the Formal Endpoint (Secure Enclave)

Encrypt on the Connector

Add Notion MCP and complete OAuth

Verify end to end

Inspect encrypted tokens in Claude Code (macOS)

Troubleshooting

Next Steps