stonega/cusco/cusco-mcp-setup
Claude Code and agent skill by stonega/cusco
- community
Checking that the SKILL.md file is still in the repository.
Use this skill whenever a user wants to configure, add, troubleshoot, document, or explain Model Context Protocol (MCP) servers for Cusco, including mcp.json, stdio servers, Streamable HTTP servers, MCP tool naming, resources, prompts, reload steps, or why Cusco is not showing an MCP tool.
Install
npx vskill@latest install stonega/cusco/cusco-mcp-setupSKILL.md
The same SKILL.md was published earlier as stonega/cusco/cusco-mcp-setup.
Cusco MCP Setup
Use this skill to help a user set up MCP servers for Cusco, the native GNOME AI chat app.
Cusco includes a compact version of this MCP setup guidance as an always-available built-in skill. Use this longer file as a reference version or when installing the same guidance into another agent.
Cusco supports MCP in Agent Mode. Enabled MCP servers are discovered into namespaced tools such as mcp__server__tool. Servers can also expose helper tools for resources and prompts when the server supports them.
First Checks
Before editing anything, identify what the user is trying to connect:
- Stdio MCP server: a local command that Cusco starts, using
command,args, optionalcwd, and optionalenv. - Streamable HTTP MCP server: a remote or local URL, using
urland optionalheaders. - Existing broken setup: inspect the config JSON, server command, environment variables, and Cusco reload state.
If you are working as a coding agent, respect the current filesystem sandbox and approval rules before writing outside the repo. Cusco's runtime config usually lives in the user's home config directory, not inside the project checkout.
Runtime Paths
Cusco loads MCP servers from:
Cusco discovers installed skills from:
The skill folder can also be registered manually from Preferences -> Skills -> Add skill folder.
Preferred mcp.json Shape
Prefer a top-level mcpServers object. Cusco also accepts servers or a bare object/array, but mcpServers is the clearest format.
Stdio server example:
Streamable HTTP server example:
Cusco infers transport from the config:
urlpresent meansstreamable-http.- No
urlmeansstdio.
Only set transport explicitly when that helps clarity or when matching an existing config style.
Important Fields
command: executable for a stdio server. Use an absolute path or a program known to be on Cusco'sPATH.args: command arguments for stdio servers. Use absolute paths for server files.cwd: working directory for stdio servers.env: string map of environment variables for stdio servers.url: Streamable HTTP MCP endpoint.headers: string map of HTTP headers for Streamable HTTP servers.enabled: defaults to true unlessdisabled: trueis set.namespace: optional stable namespace for tool names. Cusco sanitizes names to lowercase letters, numbers, and underscores.permissionPolicy: defaults toask. Useallowonly for trusted servers with low-risk tools.
Do not commit real API keys, bearer tokens, or other secrets into the repository. For examples, use placeholders.
Reload and Use in Cusco
After editing mcp.json:
- Open Cusco Preferences.
- Go to MCP or Workspace preferences.
- Use the MCP config file refresh/reload action.
- Start or continue an Agent Mode chat.
- Look for tools named like
mcp__<namespace>__<tool>.
If the server exposes resources, Cusco adds:
mcp__<namespace>__list_resourcesmcp__<namespace>__read_resource
If the server exposes prompts, Cusco adds:
mcp__<namespace>__list_promptsmcp__<namespace>__get_prompt
Verification
When working inside the Cusco repo, run the focused MCP smoke test:
For a broader check, run:
The smoke test uses tests/fixtures/fake-mcp-server.js and verifies parsing, stdio discovery, tool registration, resource helpers, prompt helpers, and tool calls.
Troubleshooting
If Cusco does not show the MCP server or tools:
- Confirm
mcp.jsonis valid JSON. - Confirm the server entry is enabled and not marked with
disabled: true. - Reload the MCP config from Preferences after editing.
- For stdio, run the command and arguments manually from a terminal to catch missing executables, bad paths, or missing environment.
- Use absolute paths for local server scripts and
cwd. - For HTTP, confirm the URL is the MCP endpoint and required headers are present.
- Set a simple
namespaceif generated tool names are confusing or collide. - Keep
permissionPolicy: "ask"while diagnosing so tool calls remain visible and auditable.
Response Pattern
When helping a user set up MCP for Cusco, include:
- The exact config path to edit.
- A minimal
mcpServersJSON block tailored to their server. - How to reload the config in Cusco.
- How the resulting tool names will look.
- A verification step, using
gjs -m tests/mcp-smoke.jsonly when the user is working in the Cusco repo.
Security
- Security scanPassed, 90 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingexamples/skills/cusco-mcp-setup/SKILL.md
Popularity
- 7-day trend score
- 0
Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/stonega/cusco/cusco-mcp-setup)