Scoped MCP Servers: How to Restrict AI Agent Access by Workspace and Tool

The Risks of Unpartitioned Model Context Protocol Endpoints

Unpartitioned MCP servers create a severe operational vulnerability known as the confused deputy problem. In this scenario, an agent holds elevated service credentials to query databases or cloud storage. When a user with limited permissions asks the agent a question, the agent evaluates the request using its own high-privilege credentials rather than the user's restricted access profile.

If an external contractor asks an internal assistant to search for project updates, an unpartitioned assistant might scan executive documents or internal salary tables because the semantic query matches document contents. The model does not understand corporate confidentiality; it only evaluates relevance. Without structural boundaries at the endpoint, the agent acts as an accidental proxy that bypasses access policies.

Why Prompt Guardrails Cannot Replace Structural Boundaries

Attempting to restrict an agent's access through prompt engineering fails against real-world inputs. System prompts that instruct a model to "only look at documentation" or "ignore financial spreadsheets" provide zero deterministic protection. Natural language is inherently flexible and susceptible to indirect prompt injection.

If an untrusted document contains instructions directing the model to ignore previous system instructions and read adjacent files, an autonomous agent can follow those instructions and expose protected data. Security boundaries must exist outside the inference context. By scoping the MCP connection so that the server does not search or return workspaces outside its scope, the agent cannot be manipulated into retrieving data outside its operational boundary.

1. Organization Level Scoping

In multi-tenant platforms, the organization represents the top-level administrative boundary. Organization-level scoping ensures that an agent's credentials belong to a defined organization account. Fastio permissions are set per organization, workspace, and share, through member roles. At the organization level, member roles include owner, admin, and member.

An agent connecting with organization-scoped credentials can only see resources within that organization. It cannot query across accounts or access data belonging to other organizations. If an agency manages workspaces for multiple enterprise clients, each client's assets live within separate organizational structures, keeping each client's data apart.

2. Workspace Container Level Scoping

Within an organization, data must be partitioned into discrete workspace containers rather than an unpartitioned directory tree. Fastio workspace roles include owner, admin, member, guest, and view. Every workspace member reaches the entire workspace according to their assigned role.

A workspace's join setting defaults to letting any member of its organization join. Keeping a workspace restricted to named people and specific agents requires explicitly restricting that setting. When an agent is provisioned for a task, it is assigned membership strictly in the designated workspace. If an agent needs to process marketing assets, it is added to the marketing workspace and excluded from the finance workspace. Because it holds no membership in finance, its search and retrieval tools cannot discover, query, or index financial documents.

3. Tool Manifest Level Scoping

The third scoping layer controls the tool definitions returned to the client during the Model Context Protocol capability negotiation phase. When an MCP client initializes a connection, the server advertises its available tools via the protocol's tools discovery method.

Tool manifest scoping dynamically filters this list based on the agent's authorization. If an agent is granted Read Only access, the server completely omits state-changing tools from the advertised manifest. If a tool like storage_manage or workspace_manage is not included in the manifest, the language model has no schema for it and cannot generate calls to modify, move, or delete files.

Interactive OAuth Scoping for Human-Driven Clients

Interactive clients, such as Claude Desktop, the Claude web interface, mobile apps, and ChatGPT, connect to remote MCP servers using OAuth 2.0. During the OAuth connection handshake, the user is redirected to a browser-based authentication window.

Fastio's OAuth flow presents a Review Permissions screen where the user explicitly chooses:

• Permission Level: The user selects either Read Only or Read & Write access.
• Target Workspaces: The user selects the exact organizations and workspaces the connection can reach.

When a user selects a Read Only connection, tools that change data are not offered at all. Because write tools are excluded from the tool manifest, there is no 403, no insufficient_scope error, and no step-up flow during execution. The model never sees the mutation tools, eliminating execution errors and prompt injection vectors that attempt to force file edits.

Headless API Key Scoping for Automated Pipelines

Background automation agents running in continuous integration pipelines, scheduled cron tasks, or server environments operate headlessly without a human in the browser loop. These agents connect using scoped API keys sent over Streamable HTTP as an Authorization: Bearer <api key> header.

API keys carry explicit scopes and act with the permissions of the user who created them; they have no role of their own. If an administrator creates an API key scoped to a single project workspace with read-only permissions, the agent using that key cannot execute file uploads or modifications. Because the key acts with its creator's permissions, reducing the creator's role also reduces what the key can do.

Segregating Read Tools from Mutation Tools

To enforce least privilege at the tool level, the Fastio MCP server divides operations across dedicated read tools and mutation tools.

When connecting to https://mcp.fast.io/mcp/tools (used for Claude apps and general MCP clients), operational boundaries are split into distinct tool pairs:

• Read Tools: storage, workspace, upload, and share handle read-only operations including searching files, listing directory contents, inspecting workspace details, and retrieving metadata.
• Management Tools: storage_manage, workspace_manage, upload_manage, and share_manage handle state-changing actions such as deleting files, moving items, creating shares, and managing locks.

For coding agents connecting to https://mcp.fast.io/mcp/code, the available tools are auth, auth_manage, upload, upload_manage, search, execute, execute_manage, and how-to. The execute tool handles GET requests for inspecting data, while write and mutation actions are isolated to execute_manage. On a Read Only session, a write sent through a read tool is refused by the server.

Cloud Sync and Permission Boundary Realignment

Organizations often maintain existing document repositories in Google Drive, Dropbox, Box, or OneDrive (including SharePoint document libraries accessed through the OneDrive connector). Fastio's Cloud Sync connects these external folders directly to a workspace, operating one-way or two-way, on a schedule or on demand. Cloud Sync never runs continuous, live, or real-time sync.

When files sync into a Fastio workspace, they inherit the destination workspace's container permissions. Source drive permissions, external sharing links, and inherited access lists do not carry over. What an agent can retrieve is decided strictly by Fastio workspace membership rather than by legacy sharing settings in the source system. If an external folder had overly permissive sharing in Google Drive, syncing it into a private Fastio workspace limits it to that workspace's members.

Advisory File Locks and Multi-Agent Versioning

In workflows where multiple agents or human teammates collaborate within the same workspace, concurrent file writes can cause race conditions. Fastio provides advisory per-file locks in workspace or share storage, managed via MCP actions: lock-acquire and lock-release on storage_manage, and lock-status on storage.

An advisory lock signals to other participants that an agent is actively working on a file. The lock expires automatically unless heartbeated by the holder. Crucially, an advisory lock never grants exclusive write rights or prevents writes: concurrent writes both land safely, and per-file version history preserves every version. Teammates and administrators can inspect previous versions and restore earlier states without data loss.

Auditing Structural Changes in the Activity Log

Verifying access control requires an accurate record of operational changes. Fastio provides a detailed activity log that records what changed and who changed it across the organization, covering actions by people and agents alike.

The activity log tracks file uploads, edits, moves, and deletions, along with membership adjustments, role changes, and share creation. It does not record read-only events such as views, downloads, opens, or previews. Security teams use the activity log to audit administrative events, such as when an agent was added to a workspace or when a public share was created, maintaining clear visibility into system configuration.

Connecting Claude Code via Streamable HTTP

In Claude Code, you can add the Fastio MCP server directly from your terminal using Streamable HTTP:

claude mcp add --transport http fast-io https://mcp.fast.io/mcp/code

Claude Code supports scoping configurations to control where server settings are stored:

• Project Scope (--scope project): Saves the server configuration to .mcp.json at the root of your project repository, allowing team members to share the tool definition via version control.
• Local Scope (--scope local): Saves the configuration private to your local environment in ~/.claude.json.

After adding the server, authenticate using claude mcp login fast-io to initiate browser-based OAuth authentication. Select your target workspace container and choose your permission level on the Review Permissions screen.

Configuring Cursor and IDE Clients

For IDE coding environments like Cursor, define the server connection in your project configuration at .cursor/mcp.json or your global configuration at ~/.cursor/mcp.json:

{
  "mcpServers": {
    "fast-io": {
      "url": "https://mcp.fast.io/mcp/code"
    }
  }
}

For VS Code and GitHub Copilot agent mode, configure .vscode/mcp.json under the "servers" key using "type": "http" and "url": "https://mcp.fast.io/mcp/code". For Cline, configure the connection with "type": "streamableHttp" and the /mcp/code URL.

Extracting Structured Context with Metadata Views

While semantic search through Intelligence Mode helps agents query unstructured text, autonomous workflows frequently need structured records from documents like contracts, invoices, and technical specs. Fastio provides Metadata Views, which turn workspace documents into queryable, typed databases.

Users and agents describe the required fields in natural language, and the system designs a schema supporting Text, Integer, Decimal, Boolean, URL, JSON, and Date & Time formats. Without templates or OCR rules, Metadata Views match documents across the workspace and populate structured tables. Agents can query these structured views through MCP tools, extracting exact operational figures without processing entire files.

Platform Plans and Subscription Options

Fastio provides an intelligent workspace platform designed for agentic teams and human collaboration. Monthly plans start with a 14-day free trial, which requires a credit card and ends early if trial credits run out.

Review current Fastio pricing and plans across standard organizational tiers:

Credits meter AI work only. Storage beyond the plan is $0.015 per GB a month, and extra bandwidth is $0.04 per GB, billed in money.