Protocol Ecosystem
DotAgents integrates five complementary protocols that together form a complete agent orchestration platform. Each protocol answers a different question:
| Protocol | Question It Answers |
|---|---|
| MCP | "What tools can I access?" |
| ACP / acpx | "What agents can I delegate to, and what runtime executes them?" |
| Skills | "What knowledge do I have?" |
| Agents | "Who am I and how am I configured?" |
| .agents/ | "How is my configuration stored and shared?" |
MCP — Model Context Protocol
MCP is Anthropic's open protocol for connecting AI models to tools and resources. DotAgents acts as an MCP client that connects to MCP servers.
How It Works
DotAgents (MCP Client)
│
├── stdio transport ──→ Local MCP Server (process)
├── WebSocket ──→ Remote MCP Server
└── streamableHttp ──→ HTTP MCP Server (with OAuth 2.1)
Tool Discovery
When an MCP server connects, DotAgents discovers all available tools and makes them callable by the AI agent. Tools are namespaced: {serverName}:{toolName}.
Key Capabilities
- Three transport types: stdio (local), WebSocket, streamableHttp (remote)
- OAuth 2.1: Automatic token refresh for protected servers
- Tool approval: Optional user confirmation before execution
- Parallel execution: Concurrent tool calls when possible
- Real-time progress: Live UI updates during tool execution
ACP + acpx — Agent Delegation Runtime
ACP is a protocol for agent-to-agent communication and delegation. DotAgents now uses the acpx CLI as its external ACP runtime instead of speaking ACP transport directly.
Delegation Flow
User Request
│
▼
Main Agent (internal)
│
├── Sees available agents in prompt context
├── Decides to delegate to "code-agent"
├── Calls delegate_to_agent
│
▼
ACP Router
│
├── Looks up agent in registry
├── Spawns process (e.g., claude-code-acp --acp)
├── Sends JSON-RPC request
│
▼
External Agent
│
├── Processes task
├── Requests permissions (bidirectional)
├── Returns results via streaming
│
▼
Results → Main Agent → User
Connection Types
| Type | Description | Example |
|---|---|---|
| Internal | Runs within DotAgents | Default agent |
| acpx | Runs an ACP-compatible local agent through acpx | Claude Code, Auggie |
| Remote | Connects to HTTP endpoint | Cloud-hosted agents |
Bidirectional Communication
ACP isn't one-way. Sub-agents can request things from the parent:
- File read/write permissions
- User approval for actions
- Access to shared resources
Skills
Skills are instruction-based capability extensions based on Anthropic's Agent Skills specification. They extend agents with specialized knowledge without code changes.
How Skills Work
Agent System Prompt includes:
"Available Skills:
- document-processing: Create, edit, and analyze .docx files
- code-generation: Generate and refactor code"
Agent decides to use a skill
│
▼
Agent reads the listed SKILL.md path with execute_command
│
▼
Full instructions loaded from .agents/skills/<id>/SKILL.md
│
▼
Agent uses skill knowledge to complete the task
Skill Properties
- Portable — Work across DotAgents, Claude Code, Cursor
- Composable — Agents can use multiple skills together
- Shareable — Export and import via agent bundles
- Versioned — Track changes in git alongside your code
Agents
Agents consolidate identity, behavior, model choice, tool access, skills, and connection mode. The desktop API and TypeScript type still call this shape AgentProfile internally.
Agent Components
AgentProfile
├── Identity (id, name, displayName, description, avatar)
├── Behavior (systemPrompt, guidelines, properties)
├── Model Config (provider, model override)
├── Tool Config (enabled/disabled servers and tools)
├── Skills Config (which skills are active)
├── Connection (how to run: internal, acpx, acp, stdio, remote)
└── State (enabled, isDefault, role)
Tool Access Control
Agents have fine-grained tool access:
- enabledServers — Whitelist of MCP servers
- disabledServers — Blacklist of MCP servers
- disabledTools — Specific tools to block
- enabledRuntimeTools — Whitelist of DotAgents runtime tools
When enabledRuntimeTools is omitted, agents get the filesystem-first default runtime tools: set_session_title, execute_command, read_more_context, and mark_work_complete. Runtime discovery metadata lives under $DOTAGENTS_RUNTIME_DIR, with agents.json, tools/index.json, and per-tool schemas in tools/schemas/.
How They Work Together
┌─────────────────────────────────────────────────────────────┐
│ .agents/ Protocol │
│ (Configuration Layer) │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Agents │ │ Skills │ │ Knowledge │ │
│ │ │ │ │ │ & Notes │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
└─────────┼─────────────────┼─────────────────┼───────────────┘
│ │ │
▼ ▼ ▼
┌──────────────────────────────────────────────────────┐
│ Core Agent Engine │
│ │
│ Agent config defines WHO the agent is │
│ Skills define WHAT the agent knows │
│ Notes provide durable CONTEXT across sessions │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ MCP Service │ │ ACP Service │ │
│ │ (Tool Access) │ │ (Delegation) │ │
│ └────────┬─────────┘ └────────┬─────────┘ │
└───────────┼──────────────────────┼────────────────────┘
│ │
▼ ▼
┌───────────────┐ ┌───────────────┐
│ MCP Servers │ │ ACP Agents │
│ (Tools) │ │ (Sub-agents) │
└───────────────┘ └───────────────┘
Complete Flow Example
- App starts → Loads
.agents/config (global + workspace layers) - Agent initialized → Agent config loaded, skills indexed, relevant notes resolved
- User speaks → Voice transcribed, sent to agent
- Agent reasons → Uses skills knowledge, checks available tools
- Agent acts → Calls MCP tools or delegates to ACP agents
- Results returned → Displayed to user, saved to conversation history
- Note updated → Relevant context persisted for future sessions
Next Steps
- MCP Tools — Configure and use MCP tool servers
- Agents — Create specialized agents
- Skills — Build portable agent capabilities
- Multi-Agent Delegation — Set up
acpx/ACP coordination