Model Context Resources

Model Context Resources are reusable capability packages that can give an agent tools, prompts, resources, or external context. In the product they usually appear as Connections in project navigation, workspace settings, task personalization, and Agent Pack configuration.

The shorthand MCR is common internally, but user-facing docs should prefer Model Context Resource on first mention.

What a Model Context Resource contains

A Model Context Resource has a name, URI, type, project scope, optional configuration, and optional snapshot of its tool surface. Depending on the type, it can point to a flow, integration, index, skill collection, workspace container, external MCP server, or Agent Pack.

The important user-facing idea is simple: a Model Context Resource is the thing an agent connects to when it needs a capability.

Examples:

• A Gmail connection that exposes mail tools.
• A project knowledge index that exposes search tools.
• A flow-backed tool suite exported as a model context.
• A shared skills collection.
• A remote MCP server connected through OAuth.
• An Agent Pack that bundles several resources and skills into one external interface.

Project and shared resources

Most Model Context Resources are project-scoped. They live in one project and are configured from that project's Connections area.

Some resources can be marked as shared. A shared resource is still owned by its source project, but other projects in the account can discover and use it through the shared-resource path. Shared resources keep their owning project context so tools run against the correct underlying project, integration, skills collection, or flow.

Use shared resources when one project owns a reusable capability that other projects should consume without copying it. For example, a source project can own a shared skills collection or shared flow-backed resource, and target projects can attach that shared resource to workspaces or Agent Packs.

Resource types

BotDojo supports several Model Context Resource types:

Type	What it represents
flow	A flow-backed model context. Loading it runs a target flow that returns tools, prompts, or resources.
index	A knowledge index exposed as search or full-context tools.
integration	A BotDojo integration connection, such as an external app tool suite.
container_mcp_server	A container-backed MCP server.
storage	BotDojo storage and document resources exposed as tools.
external_mcp_server / remote_mcp	An external MCP server connected to BotDojo, often through OAuth.
skills, skills_collection, skills_entity_collection	Skill collections and skill-management resources.
workspace_mcp	A resource that connects to an existing workspace container.
agent_pack	A beta bundle that exposes selected resources, skills, and optional workspace controls through MCP.

Some types are meant mostly for internal platform composition, while others are what users see as project connections.

Snapshots

A Model Context Resource can store a snapshot of its discovered tool surface. The snapshot records tools, resources, prompts, discovery time, and errors.

Snapshots help the UI and agents understand what a resource exposes without opening the backing server every time. They are especially useful for showing available tools, filtering tool access, and making connection configuration predictable.

Some resources have dynamic tools. Dynamic resources may refresh their snapshot on use because their tool surface can change.

Exporting as MCP and CLI

Model Context Resources can be exposed through MCP so compatible clients can discover resources, read resource content, and call tools.

The Agent Pack CLI flow is currently beta. The botdojo-tool CLI uses a project Resource Token to register with the MCP gateway, receive approved credentials, list Agent Pack tools, search resources, read resources, and call tools inside child Model Context Resources.

Typical CLI actions include:

• List exposed MCP tools.
• Load agent_context.
• Search resources exposed by the Agent Pack.
• Read a resource such as a TOOLS.md URI.
• Call a tool inside a child resource.
• Search or view skills included in the pack.

This makes BotDojo capabilities usable outside the BotDojo web app while still enforcing BotDojo authorization.

How workspace agents use resources

Workspace agents receive Model Context Resources through workspace connection settings. The workspace's connection config determines which resources are enabled, which tools are visible, and whether tool calls can run directly or must ask for approval.

In a workspace, enabled resources can be used in several ways:

• The composer can attach resources with @.
• The agent can search or open resources when Resource MCP tools are available.
• Skills can reference resources they require.
• Workspace file resources can be opened and attached through workspace://files/....
• Agent-local resources such as agent://me/... can expose agent controls, skills, scheduler tools, and sub-agent tools.

Workspace settings are copied from task personalization or templates when a workspace is created, then saved on the workspace. That means existing workspaces keep their own resource access even if project defaults change later.

Agent Packs (beta)

Agent Packs are beta Model Context Resources that bundle a curated set of Model Context Resources and skills behind one MCP-facing package.

An Agent Pack can expose:

• Selected child Model Context Resources.
• Selected skills collections.
• Agent context such as instructions and memory.
• Optional workspace-backed controls through agent://me and workspace://mcp.

Agent Packs are useful when you want to plug BotDojo capabilities into other systems. Instead of integrating each connection separately, an external MCP client can connect to the Agent Pack and use its resource search, resource read, and tool-call surface.

Agent Pack permissions can work in two modes:

• Explicit - The pack uses its own curated connection config.
• Inherit caller - The pack mirrors the caller's effective permissions.

In explicit mode, the pack's connections config decides which child resources are available. Changes to the pack's child resource list may require a new MCP session before external clients see the update.

Permission model

Permissions are evaluated at two levels: resource access and tool access.

Resource access controls whether an agent can see or use a Model Context Resource:

• Open - The resource is available without a human approval step.
• Requires approval - The resource is visible, but use requires approval.
• Denied - The resource is hidden or blocked for that workspace, agent, or pack.

Tool access controls individual tools inside a resource:

• Invoke - The tool can run directly.
• Ask - The tool requires approval before running.
• Block - The tool is hidden or unavailable.

Connection settings use stable permission keys such as mcr:<id> when possible, with URI snapshots for traceability. This lets BotDojo keep permissions stable even if a resource URI or display name changes.

Calling user and agent identity

When a user runs a workspace agent, there are two identities to consider:

• Calling user - The human who started or approved the task.
• Agent identity - The agent the task is running as.

The agent identity supplies the agent's instructions, memory, skills, and configured permissions. The calling user still matters because the agent should not become a way to bypass the user's authorization.

For run-as-agent execution, BotDojo can include the initiating user's policy context. Resource access can then account for both the running agent and the user who initiated the run. If the initiating policy context is missing, the system treats that as an operational signal because it can affect access to shared resources.

External MCP access through Resource Tokens also has an identity and approval flow. A Resource Token registers a client, creates an approval request for the token owner, and issues MCP credentials only after approval.

Personal agents vs shared agents

Personal agents and shared workspace agents should be treated differently.

Personal agents

Personal agents are meant for an individual's task workspace. Their security boundary is project-scoped but intentionally constrained for personal use. Personal workspace capability policies can limit which integration providers, remote MCP servers, and container MCP resources a user can create or attach.

Use a personal agent when the work should follow one user's connections, personal defaults, and private task context.

Shared agents and workspace agents

Shared agents and workspace agents are meant for project work. They may use project connections, shared resources, scheduled tasks, and workspace files. Their connection configuration should be reviewed as a project-level capability surface because multiple users may rely on the same workspace or Agent Pack.

Use a shared agent or project workspace when the work belongs to a project, should use project-owned connections, should be repeatable by others, or should be exposed externally through an Agent Pack.

Practical guidance

• Use project Connections for reusable project-owned capabilities.
• Use shared resources when one project owns a capability that other projects should consume.
• Use workspace connection settings to narrow what a specific workspace agent can access.
• Use approval-required access for tools that can send messages, mutate records, spend money, or affect external systems.
• Use Agent Packs when external MCP or CLI clients need a curated BotDojo capability bundle.
• Keep personal agents focused on individual workflows, and use shared workspace agents for project workflows.