Skip to content

Commit c3f13f8

Browse files
maartenbamaartenba
committed
Add documentation on AI Agent Skills and MCP Server for Duende-specific tooling
1 parent e6fe5e8 commit c3f13f8

1 file changed

Lines changed: 268 additions & 0 deletions

File tree

‎astro/src/content/docs/general/ai-agent-tools.mdx‎

Lines changed: 268 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,268 @@
1+
---
2+
title: "AI Agent Skills and MCP Server"
3+
description: "Enhance your AI coding assistant with Duende-specific knowledge using Agent Skills for domain expertise and an MCP server for documentation and samples retrieval."
4+
date: 2026-03-23
5+
sidebar:
6+
label: "AI Agent Tools"
7+
order: 5
8+
---
9+
10+
import { LinkCard, CardGrid, TabItem, Tabs } from "@astrojs/starlight/components";
11+
12+
When you use AI coding assistants with Duende products, you may find that general-purpose models lack deep expertise on Duende-specific configuration patterns, protocol nuances, and production best practices. Generic responses can miss critical details, like how to configure refresh token rotation, set up a federation gateway, or wire IdentityServer into .NET Aspire.
13+
14+
To address this, Duende provides two complementary tools that give your AI coding assistant specialized knowledge: **Duende Agent Skills** and the **Duende Documentation MCP Server**. You can use either or both, depending on your workflow.
15+
16+
Agent Skills and the MCP server address different aspects of the same problem and work well together:
17+
18+
* **Agent Skills** provide *knowledge*: structured, curated guidance on *what* to look up, *when*, and *how* to apply it. They are static files that run locally in your development environment. When your AI assistant encounters an identity-related task, skills give it the judgment to produce accurate, Duende-specific answers.
19+
* **MCP Server** provides *tools*: search, fetch, and sample retrieval against the full Duende documentation, blog, and sample code. It runs as a local server process and gives the AI assistant direct access to the latest published content.
20+
21+
Think of skills as the expertise and the MCP server as the reference library. Skills help the AI *know what to do*; the MCP server helps it *look things up*. Together, they give your AI assistant both deep domain knowledge and access to up-to-date authoritative content.
22+
23+
## Which Tool Should You Use?
24+
25+
Choose the approach that fits your workflow:
26+
27+
* **Want domain expertise baked into every response?** Install Agent Skills. Your AI assistant will automatically use the relevant skill when it encounters identity-related tasks.
28+
* **Want to search and fetch the latest docs and samples?** Register the MCP Server. Your AI assistant gains tools to look up current documentation on demand.
29+
* **Want both?** Install both. They are independent and complementary: skills provide structured knowledge while the MCP server provides live content retrieval.
30+
31+
<CardGrid>
32+
<LinkCard
33+
description="Installation instructions, skill catalog, and benchmarks"
34+
href="https://github.com/DuendeSoftware/duende-skills"
35+
title="Get Started with Agent Skills"
36+
target="_blank"
37+
/>
38+
<LinkCard
39+
description="Setup instructions for VS Code, Rider, and Claude Code"
40+
href="https://github.com/DuendeSoftware/products/blob/main/docs-mcp/README.md"
41+
title="Get Started with the MCP Server"
42+
target="_blank"
43+
/>
44+
</CardGrid>
45+
46+
## Agent Skills
47+
48+
Duende IdentityServer Agent Skills are a set of `SKILL.md` files following the open [Agent Skills format](https://agentskills.io/). Each skill is a structured knowledge module covering a specific area of identity and access management.
49+
50+
### What They Cover
51+
52+
The skills library includes a number of skills and specialized agents across these areas:
53+
54+
* **IdentityServer configuration and hosting**: setup, middleware pipeline, clients, resources, scopes, signing credentials, server-side sessions, Dynamic Client Registration (DCR)
55+
* **Token management**: token types, refresh token rotation, token exchange, DPoP, mTLS, Pushed Authorization Requests (PAR), FAPI 2.0 compliance
56+
* **API protection**: JWT bearer authentication, reference token introspection, scope-based authorization, proof-of-possession
57+
* **UI flows**: login, logout, consent, error pages, federation gateways, external providers, Home Realm Discovery
58+
* **ASP.NET Core authentication and authorization**: OIDC, JWT Bearer, cookies, policies, claims-based authorization
59+
* **Duende BFF**: Backend-for-Frontend security for SPAs, session management, API proxying
60+
* **Deployment and operations**: reverse proxy configuration, data protection, health checks, OpenTelemetry, key management, SAML 2.0
61+
* **Testing**: integration testing with `WebApplicationFactory`, mock token issuance, protocol validation
62+
* **Specialized agents**: an IdentityServer specialist and an OAuth/OIDC specialist for complex troubleshooting
63+
64+
:::note
65+
Agent Skills focus on **identity and security**. For general .NET development skills (C# coding standards, EF Core, dependency injection, concurrency patterns, .NET Aspire, and more), consider exploring [dotnet-skills](https://github.com/Aaronontheweb/dotnet-skills) alongside Duende skills. The two sets are complementary with no overlap.
66+
:::
67+
68+
### Setup
69+
70+
Clone the [Duende Agent Skills](https://github.com/DuendeSoftware/duende-skills) repository and copy the skill folders into the skills directory for your AI coding assistant.
71+
72+
Each skill is a folder containing a `SKILL.md` file. Copy the individual skill folders into the path your AI assistant expects:
73+
74+
| AI Coding Assistant | Skills Path |
75+
|:--------------------|:-----------------------------|
76+
| GitHub Copilot | `.github/skills/` |
77+
| Claude Code | `.claude/skills/` |
78+
| OpenCode | `~/.config/opencode/skills/` |
79+
| Cursor | `.cursor/skills/` |
80+
| Gemini CLI | `.gemini/skills/` |
81+
| Codex CLI | `.codex/skills/` |
82+
83+
For example, to set up skills for GitHub Copilot:
84+
85+
<Tabs>
86+
<TabItem label="Windows (PowerShell)">
87+
```powershell title="PowerShell"
88+
git clone https://github.com/DuendeSoftware/duende-skills.git
89+
New-Item -ItemType Directory -Force -Path .github\skills
90+
Copy-Item -Recurse duende-skills\skills\* .github\skills\
91+
```
92+
</TabItem>
93+
<TabItem label="macOS / Linux">
94+
```bash title="Terminal"
95+
git clone https://github.com/DuendeSoftware/duende-skills.git
96+
mkdir -p .github/skills
97+
cp -r duende-skills/skills/* .github/skills/
98+
```
99+
</TabItem>
100+
</Tabs>
101+
102+
Adjust the target path for your AI coding assistant (see the table above). For example, replace `.github/skills/` with `.claude/skills/` for Claude Code, or `~/.config/opencode/skills/` for OpenCode.
103+
104+
Once the skill folders are in place, your AI assistant discovers and loads them automatically. No further configuration is needed. When your assistant encounters an identity-related task like configuring token lifetimes or setting up an external provider, it loads the relevant skill without any explicit prompting from you.
105+
106+
### Verify It Works
107+
108+
Ask your AI assistant an identity-specific question, for example: `How do I configure refresh token rotation in IdentityServer?`. If the skills are loaded correctly, the response references Duende-specific configuration and mentions IdentityServer options like `RefreshTokenUsage`.
109+
110+
### Measured Impact
111+
112+
Every skill is evaluated using realistic prompts with concrete assertions. In benchmarks, AI responses with skills loaded significantly outperform baseline responses, with the biggest gains in deeply Duende-specific areas like UI flows, API protection, and SAML configuration.
113+
114+
See the repository for the latest benchmark results, or run them against your model of choice.
115+
116+
<LinkCard
117+
description="Installation instructions, full skill catalog, and benchmark results"
118+
href="https://github.com/DuendeSoftware/duende-skills"
119+
title="Duende Agent Skills"
120+
target="_blank"
121+
/>
122+
123+
## MCP Server
124+
125+
The Duende Documentation MCP Server implements the open [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) to give AI coding assistants direct access to Duende documentation, blog posts, and sample code. It runs locally and uses SQLite full-text search to index content from multiple sources.
126+
127+
### What It Can Do
128+
129+
The MCP server provides several tools to your AI assistant:
130+
131+
* **Free-text search** across documentation, blog posts, or samples
132+
* **Fetch a specific page** from the documentation site
133+
* **Get all content for a sample**: retrieve the full code of a Duende sample project
134+
* **Get a specific file from a sample**: retrieve individual files from sample code
135+
136+
The server indexes content from three sources, keeping its local database up to date with background indexing:
137+
138+
* **Documentation**: parsed from the Duende documentation site's [`llms.txt`](https://docs.duendesoftware.com/llms.txt)
139+
* **Blog**: indexed from the RSS feed at [duendesoftware.com/blog](https://duendesoftware.com/blog/)
140+
* **Samples**: downloaded from GitHub, including all `.cs`, `.cshtml`, and relevant `.js` files
141+
142+
### Requirements
143+
144+
* **.NET 10 SDK**: the MCP server is distributed via the `dnx` tool included in the SDK
145+
* **Network access**: the server indexes content from remote sources (documentation site, RSS feed, GitHub)
146+
* **A compatible AI coding assistant**: any IDE or CLI tool that supports the MCP protocol
147+
148+
No Duende license is required to use the MCP server.
149+
150+
### Setup
151+
152+
To run the Duende Documentation MCP Server, you need the `dnx` tool (included in the .NET 10 SDK) in your system's `PATH`. The `dnx` tool can download and run applications packaged and distributed through NuGet.
153+
154+
Here are some examples of how to register the MCP server in your IDE:
155+
156+
<Tabs>
157+
<TabItem label="VS Code">
158+
You can register the MCP server [in your user settings](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server-to-your-user-settings) to make it available in any workspace, or add a `.vscode/mcp.json` file to your workspace:
159+
160+
```json
161+
// .vscode/mcp.json
162+
{
163+
"servers": {
164+
"duende-mcp": {
165+
"type": "stdio",
166+
"command": "dnx",
167+
"args": [
168+
"Duende.Documentation.Mcp",
169+
"--yes",
170+
"--",
171+
"--database", "/path/to/database.db"
172+
],
173+
"env": {}
174+
}
175+
}
176+
}
177+
```
178+
179+
Replace `/path/to/database.db` with the location where the MCP server should store its SQLite index.
180+
</TabItem>
181+
<TabItem label="JetBrains Rider">
182+
In Rider settings, navigate to **Tools | AI Assistant | Model Context Protocol (MCP)**. Add a new MCP server, select **As JSON**, and enter:
183+
184+
```json
185+
{
186+
"mcpServers": {
187+
"duende-mcp": {
188+
"command": "dnx",
189+
"args": [
190+
"Duende.Documentation.Mcp",
191+
"--yes",
192+
"--",
193+
"--database", "/path/to/database.db"
194+
]
195+
}
196+
}
197+
}
198+
```
199+
200+
Replace `/path/to/database.db` with the location where the MCP server should store its SQLite index.
201+
</TabItem>
202+
<TabItem label="Claude Code">
203+
Run the following command:
204+
205+
```powershell title="PowerShell"
206+
# Windows (PowerShell)
207+
claude mcp add --transport stdio duende-mcp `
208+
-- dnx Duende.Documentation.Mcp --yes `
209+
-- --database C:\path\to\database.db
210+
```
211+
212+
```bash title="Terminal"
213+
# macOS / Linux
214+
claude mcp add --transport stdio duende-mcp \
215+
-- dnx Duende.Documentation.Mcp --yes \
216+
-- --database /path/to/database.db
217+
```
218+
219+
Replace the database path with the location where the MCP server should store its SQLite index.
220+
</TabItem>
221+
</Tabs>
222+
223+
The MCP server creates its SQLite database at the path you specify in the `--database` parameter. On first run, it indexes documentation, blog posts, and samples in the background. Subsequent starts reuse the existing index and refresh it incrementally.
224+
225+
### Verify It Works
226+
227+
Ask your AI assistant a Duende-specific question, for example: `What is automatic key management?`. If the MCP server is working, the response draws on the indexed documentation and references Duende-specific content. Adding `use Duende` to a prompt can help direct the AI assistant to query the MCP server when the topic could match multiple sources.
228+
229+
### Example Prompts
230+
231+
Once the MCP server is registered, you can ask your AI assistant questions like:
232+
233+
* `What is a client in OpenID Connect?`
234+
* `How can I validate a JWT token in ASP.NET Core?`
235+
* `What is automatic key management?`
236+
* `Can I add passkeys to Razor Pages? Use Duende.`
237+
238+
<LinkCard
239+
description="Setup instructions for VS Code, Rider, and Claude Code"
240+
href="https://github.com/DuendeSoftware/products/blob/main/docs-mcp/README.md"
241+
title="Duende Documentation MCP Server"
242+
target="_blank"
243+
/>
244+
245+
:::note[Securing MCP endpoints]
246+
If you are building your own MCP server and want to secure it with OpenID Connect and OAuth 2.0, see the [MCP Client sample](/identityserver/samples/clients.mdx#model-context-protocol-mcp-client) for a working example.
247+
:::
248+
249+
## Support and Feedback
250+
251+
For questions, feedback, or to report issues with either the Agent Skills or the MCP server, visit the [Duende community](https://github.com/DuendeSoftware/community/discussions).
252+
253+
<LinkCard
254+
description="Ask questions and discuss with the Duende developer community"
255+
href="https://github.com/DuendeSoftware/community/discussions"
256+
title="Duende Community Forum"
257+
target="_blank"
258+
/>
259+
260+
## Disclaimer
261+
262+
Duende's AI developer tools (including the Duende Documentation MCP Server and Duende Agent Skills) are designed
263+
to provide Large Language Models (LLMs) with verified, structured context from Duende's documentation and product knowledge.
264+
These tools improve the quality and relevance of AI-assisted development with Duende products, including IdentityServer,
265+
BFF and our Open Source offerings, but they do not guarantee the correctness, security, or completeness
266+
of AI-generated output. All code, configuration, and architectural decisions produced with the assistance of these tools
267+
must be reviewed and validated by qualified developers before deployment to any environment.
268+
Duende Software is not responsible for AI-generated output that results from the use of these tools.

0 commit comments

Comments
 (0)