Concepts
How Skilder Works
Understand the architecture of Skilder — how agents connect, how tools execute, and how data flows through the system.
Skilder is an MCP server that your AI agents connect to. It builds capabilities by bundling MCP tools with instructions and scripts into skills. When an agent calls a tool, Skilder authenticates the request, checks permissions, routes it to the right underlying MCP server, and returns the result.
System Overview
The remote MCP server and the runtime are two separate services. The first is the public endpoint your agent talks to; the second is where tools and scripts actually execute — potentially on your own infrastructure. Nothing executes on the MCP server, and agents never talk to a runtime directly.
Components
| Component | Technology | What It Does |
|---|---|---|
| Remote MCP Server | Node.js + MCP SDK | The public /mcp endpoint agents connect to. Terminates OAuth, holds MCP sessions, resolves skills, fans tool calls out over NATS. Executes nothing |
| API | Fastify + Apollo GraphQL | Authentication, permission checks, skill and catalog resolution, OAuth authorization server |
| Database | Dgraph (graph DB) | Stores workspaces, skills, roles, MCP configs, and their relationships |
| Message Bus | NATS | Real-time communication between the API, the MCP server, and runtimes |
| Frontend | React + Vite + Tailwind | Management console for configuring everything |
| Runtime | Distributed Node.js | Runs MCP server processes and skill scripts, and calls out to external services |
What Happens When an Agent Calls a Tool
Step by step
- Authentication — The agent sends its API key to the remote MCP server, which validates it against the API and identifies the associated role.
- Permission check — The MCP server verifies the tool belongs to a skill in that role.
- Server resolution — Looks up which MCP server provides the tool and which runtime the workspace runs on.
- Message routing — Publishes the tool call to NATS, which routes it to that runtime.
- Execution — The runtime invokes the MCP server process, which calls the external service.
- Response — The result flows back through NATS to the remote MCP server and then to the agent.
Design Principles
- Protocol-first — Implements the Model Context Protocol standard. Any MCP-compatible server works out of the box.
- Graph-native — Relationships between workspaces, skills, roles, and servers are stored as a graph, making permission resolution fast and flexible.
- Event-driven — NATS decouples the API from runtime execution. This enables horizontal scaling and reliable message delivery.
- Real-time — WebSocket subscriptions keep the UI in sync with backend state. No polling needed.