> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Guardrails for Unknown MCPs and Skills

> Choose whether MCP servers and skills outside your Catalog are allowed and monitored, or blocked

## Overview

[Guardrails](https://app.formal.ai/ai-security) set the default handling for MCP servers and skills that aren't in your [Catalog](/docs/guides/ai-governance/overview#the-catalog). Items in the Catalog follow their own access controls instead.

The page has two settings:

| Setting | Applies when |
| - | - |
| **Unknown MCPs** | An agent uses an MCP server that is not in the Catalog |
| **Unknown Skills** | An agent loads a skill that is not in the Catalog |

For each setting, choose a **Default action**:

* **Allow:** Formal lets the traffic through and logs it. New items appear in [Shadow AI](/docs/guides/ai-governance/shadow-ai) for review.
* **Block:** Formal blocks the traffic. For unknown MCP servers, the agent receives a list of approved alternatives. For unknown skills, the user sees Formal's standard block message.

Changing settings requires the **Policies** permission.

## Configure a Guardrail

<Steps>
  <Step title="Open Guardrails">
    Go to [Guardrails](https://app.formal.ai/ai-security).
  </Step>

  <Step title="Choose the default action">
    Under **Unknown MCPs** or **Unknown Skills**, select **Allow** or **Block**.
  </Step>

  <Step title="Write the block message (optional)">
    With **Block** selected, enter **Message shown to blocked users**. Formal stores it as the policy's `reason`, which appears in Logs. Users don't see this text yet: they get the alternatives list or Formal's standard block message.
  </Step>

  <Step title="Save">
    Click **Save Changes**.
  </Step>
</Steps>

**Verify:** Go to [Policies](https://app.formal.ai/policies). With **Block** selected, you see **Block unknown MCPs** or **Block unknown skills**.

## What Formal Creates

Each guardrail set to **Block** is a generated [policy](/docs/guides/policies/introduction). Selecting **Allow** removes it.

### Block Unknown MCPs

The policy blocks MCP tool calls to servers that have no Formal Resource:

```rego theme={"languages":{"custom":["/languages/cel.json","/languages/rego.json"]}}
package formal.v2

import future.keywords.if

request := {
  "action": "block",
  "type": "mcp_suggest_alternatives",
  "reason": "This MCP is not approved by your organization.",
} if {
  input.resource.technology == "mcp"
  input.resource.name == ""
  input.mcp.method == "tools/call"
}
```

The `mcp_suggest_alternatives` block tells the agent which approved MCP servers it can use instead. It also explains how to request the blocked server. See [Suggest approved MCP alternatives](/docs/guides/policies/enforcement#suggest-approved-mcp-alternatives).

Only the [Formal Endpoint](/docs/guides/client-apps/desktop-app) sees MCP servers that have no Formal Resource. This guardrail applies on devices that run the Endpoint with Transparent Mode.

### Block Unknown Skills

The policy blocks LLM requests that load a skill whose name is not in an approved list:

```rego theme={"languages":{"custom":["/languages/cel.json","/languages/rego.json"]}}
package formal.v2

import future.keywords.if
import future.keywords.in

unknown_skill := {
  "approvedSkills": ["code-review", "release-notes"],
  "blockMessage": "This skill is not approved by your organization.",
}

request := {
  "action": "block",
  "type": "block_with_formal_message",
  "reason": unknown_skill.blockMessage,
} if {
  input.resource.technology == "llm"
  some skill in input.llm.loaded_skills
  not skill.name in unknown_skill.approvedSkills
}
```

`approvedSkills` holds the names of the managed skills in your Catalog. Formal updates the list when someone with the **Policies** permission opens the Catalog, Shadow AI, or Guardrails page.

Formal detects loaded skills in Claude Code traffic only, so this guardrail doesn't affect other agents. It names each loaded skill after the folder that holds its `SKILL.md`.

<Warning>
  Change guardrails from the Guardrails page, not in the policy editor. Saving
  a guardrail rewrites its generated rules. See
  [Policy Tags](/docs/guides/policies/introduction#policy-tags) to recognize
  generated policies.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="An unknown MCP server isn't blocked">
    **Cause:** The traffic doesn't pass through the Formal Endpoint, or the server has a Formal Resource. **Fix:** Confirm that a [network rule](/docs/guides/network-rules) intercepts `mcp` traffic on the device. Servers with a Formal Resource follow their Catalog access controls.
  </Accordion>

  <Accordion title="A managed skill is blocked">
    **Cause:** The skill's access controls exclude the user. **Fix:** Open the skill in the Catalog and check **Access Controls**.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Shadow AI" icon="binoculars" href="/docs/guides/ai-governance/shadow-ai">
    Review items that people already use
  </Card>

  <Card title="Access Requests" icon="user-check" href="/docs/guides/ai-governance/access-requests">
    Approve employee requests for blocked MCP servers
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.