mcp-server-creator

Original source / Raw SKILL.md

---
name: mcp-server-creator
description: >
  Create valid, production-quality Stigmer McpServer YAML files conforming to the
  agentic.stigmer.ai/v1 API. Use this skill when users want to: (1) create a new
  McpServer resource for connecting agents to external tools (GitHub, Slack, databases,
  custom APIs), (2) configure MCP server transport (stdio subprocess or HTTP endpoint),
  (3) declare environment variable requirements and credential contracts, (4) set default
  tool gates and approval policies for human-in-the-loop safety, (5) understand how agents
  reference McpServers via mcp_server_usages. Triggers on requests mentioning MCP server,
  McpServer, tool integration, or connecting an agent to an external service.
---

# MCP Server Creator

Create valid `agentic.stigmer.ai/v1` McpServer YAML resources. Follow the six-step
workflow below in order for every McpServer creation request.

## Step 1 — Understand the MCP Server

Before writing any YAML, gather these details from the user:

1. **External system** — What does the MCP server connect to? (GitHub, Slack, a database, a custom API, etc.)
2. **Server type** — Is it a CLI tool started as a subprocess (`stdio`) or a remote HTTP service (`http`)?
   - If the user mentions `npx`, `python -m`, `uvx`, a Go binary, or any CLI command → `stdio`
   - If the user mentions a URL, hosted service, or API gateway → `http`
   - When in doubt, default to `stdio` — the vast majority of MCP servers use it
3. **Credentials** — What environment variables does the server need? Which are secrets?
4. **Tools** — What tools should be enabled by default? Which tools are destructive and need approval?
5. **Ownership** — What organization owns this server? Should it be public (marketplace) or private?

If the user has already provided sufficient context, proceed directly. Do not ask questions
the user has already answered.

## Step 2 — Choose the Server Type

Exactly one of `stdio` or `http` must be specified. This is a proto `oneof` with `required` validation — omitting both or specifying both fails.

**Use `stdio`** (most common) for subprocess-based servers:
```yaml
spec:
  stdio:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
```

**Use `http`** for remote/managed services:
```yaml
spec:
  http:
    url: "https://mcp.example.com/v1"
    headers:
      Authorization: "Bearer ${API_TOKEN}"
    timeout_seconds: 45
```

For field details, see [references/schema.md](references/schema.md).

## Step 3 — Configure Environment Variables

Declare every environment variable in `env_spec.data`. For each variable:
- Set `is_secret: true` for API tokens, passwords, private keys
- Set `is_secret: false` for regions, org names, URLs, feature flags
- Write a `description` that specifies required permissions/format
- **Never pre-fill `value` for secrets** — values are provided at runtime via AgentInstance

```yaml
spec:
  env_spec:
    data:
      GITHUB_TOKEN:
        description: "GitHub personal access token with repo and read:org scopes"
        is_secret: true
      GITHUB_OWNER:
        description: "Default GitHub organization or username"
        is_secret: false
```

For HTTP servers, ensure every `${VAR_NAME}` in headers/query_params has a matching `env_spec` entry.

## Step 4 — Set Default Tools and Approval Policies

### Default Enabled Tools
Use `default_enabled_tools` to gate which tools are available by default. Empty = all tools enabled. Agents can only restrict further, never expand beyond this list.

### Default Tool Approvals
Use `default_tool_approvals` for destructive or sensitive operations. Each entry needs:
- `tool_name` — exact name from the server's `tools/list` (case-sensitive)
- `message` — approval prompt with `{{args.field}}` placeholders for context

**Tool names must be verified, not guessed.** If the user doesn't know exact tool names, recommend running `stigmer discover mcp-server <slug>` after applying, then updating the YAML with discovered names.

For the approval policy chain and message template syntax, see [references/agent-integration.md](references/agent-integration.md).

## Step 5 — Validate the YAML

Before presenting the final YAML, verify every rule in [references/validation.md](references/validation.md). Critical checks:

1. `apiVersion` is exactly `agentic.stigmer.ai/v1`
2. `kind` is exactly `McpServer` (PascalCase)
3. `metadata.name` is present
4. Exactly one of `spec.stdio` or `spec.http` is specified
5. `spec.stdio.command` is present (for stdio servers)
6. `spec.http.url` is a valid HTTP/HTTPS URL (for http servers)
7. No `status` fields are set (system-managed)
8. No secret values pre-filled in `env_spec`
9. Slug format: `^[a-z][a-z0-9-]*$`, 1–63 chars (if specified)
10. `${VAR_NAME}` syntax in HTTP headers/params (not `{{}}`)
11. `{{args.field}}` syntax in approval messages (not `${}`)

## Step 6 — Explain Agent Integration

After delivering the McpServer YAML, explain how agents reference it:

```yaml
# In an Agent spec
spec:
  mcp_server_usages:
    - mcp_server_ref:
        kind: mcp_server
        slug: <mcpserver-slug>    # matches the McpServer's metadata.slug
      enabled_tools:              # optional — subset of default_enabled_tools
        - tool_one
        - tool_two
      tool_approval_overrides:    # optional — per-agent customization
        - tool_name: dangerous_tool
          requires_approval: true
          message: "Custom approval message"
```

Key points to convey:
- The McpServer contains no secrets — credentials come from AgentInstance's environment binding
- Agents reference by `org/slug` — slug is auto-generated from `metadata.name` if not set
- The three-layer approval chain: McpServer defaults → Agent overrides → Execution bypass
- After applying, run `stigmer discover mcp-server <slug>` to populate tool metadata
- In references, use `kind: mcp_server` (snake_case), not `kind: McpServer` (PascalCase)

For complete agent integration details, see [references/agent-integration.md](references/agent-integration.md).

## Reference Files

| File | When to Read |
|------|-------------|
| [references/schema.md](references/schema.md) | Need field-level details for any McpServer spec field |
| [references/examples.md](references/examples.md) | Need complete YAML examples (minimal → marketplace-ready) |
| [references/validation.md](references/validation.md) | Need the full validation checklist before presenting YAML |
| [references/agent-integration.md](references/agent-integration.md) | Need to explain how agents reference McpServers, tool approval chain, or sub-agent access |


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/schema.md

```markdown
# McpServer YAML Schema Reference

Complete field reference for the `agentic.stigmer.ai/v1` McpServer resource.
Proto source: `ai/stigmer/agentic/mcpserver/v1/spec.proto`.

## Top-Level Structure

```yaml
apiVersion: agentic.stigmer.ai/v1    # required, exact string
kind: McpServer                       # required, exact string (PascalCase)
metadata:                             # required
  name: <string>                      # required — human-readable name
  slug: <string>                      # optional — auto-generated from name
  org: <string>                       # recommended — owning organization
  visibility: <enum>                  # optional — visibility_private (default) or visibility_public
  labels: {key: value}                # optional — filtering metadata
  annotations: {key: value}           # optional — non-filtering metadata
  tags: [string]                      # optional — categorization
spec:                                 # required
  description: <string>              # recommended — what the server does
  icon_url: <string>                 # optional — image URL for UI
  tags: [string]                     # optional — marketplace categorization
  stdio: <StdioServerConfig>         # exactly one of stdio or http (required)
  http: <HttpServerConfig>           # exactly one of stdio or http (required)
  default_enabled_tools: [string]    # optional — tool gate
  env_spec: <EnvironmentSpec>        # optional — credential contract
  default_tool_approvals: [ToolApprovalPolicy]  # optional — approval policies
# status: {} — system-managed, never set by users
```

## Metadata Fields

| Field | Required | Description |
|---|---|---|
| `name` | Yes | Human-readable name (e.g., "GitHub MCP Server") |
| `slug` | No | URL-friendly ID, unique per org. Format: `^[a-z][a-z0-9-]*$`, 1–63 chars. Auto-generated from name if omitted. This is how agents reference the server. |
| `org` | Recommended | Owning organization. Auto-resolved from context if omitted. |
| `visibility` | No | `visibility_private` (default) or `visibility_public` (marketplace). |
| `labels` | No | Key-value pairs for filtering (e.g., `category: vcs`). |
| `annotations` | No | Key-value pairs not used for filtering (e.g., `docs-url: "https://..."`. |
| `tags` | No | String array for categorization and search. |

## StdioServerConfig

Subprocess-based server communicating over stdin/stdout.

| Field | Required | Description |
|---|---|---|
| `command` | Yes | Executable to run: binary name on PATH or absolute path. Examples: `npx`, `python`, `node`, `./mcp-server` |
| `args` | No | Arguments passed to the command. Order matters. |
| `working_dir` | No | Working directory for the process. Use absolute paths. |

Credential injection: environment variables from AgentInstance are passed directly to the subprocess.

## HttpServerConfig

Remote server communicating over HTTP POST + Server-Sent Events.

| Field | Required | Description |
|---|---|---|
| `url` | Yes | Base URL of the MCP endpoint. Must be valid HTTP/HTTPS URL. |
| `headers` | No | HTTP headers for every request. Values support `${VAR_NAME}` env var substitution. |
| `query_params` | No | Query parameters appended to URL. Values support `${VAR_NAME}` substitution. |
| `timeout_seconds` | No | Request timeout (0–300). Default: 30. Set higher for long-running operations. |

**Environment variable interpolation** in headers/params uses `${VAR_NAME}` syntax — resolved at runtime from AgentInstance's environment binding.

## EnvironmentSpec (`env_spec`)

Declares required environment variables — schema only, not values.

```yaml
env_spec:
  data:
    VAR_NAME:
      value: ""                  # leave empty for secrets
      is_secret: true/false      # true = encrypted at rest, redacted in logs
      description: "What this variable is for and required format/permissions"
```

| EnvironmentValue Field | Description |
|---|---|
| `value` | Leave empty in McpServer spec. Values provided at runtime via AgentInstance. |
| `is_secret` | `true`: encrypted, redacted. `false`: plaintext, visible in audit logs. |
| `description` | Document required permissions, format, scopes. Shown in UI during AgentInstance setup. |

## ToolApprovalPolicy (`default_tool_approvals`)

Defines which tools require human approval by default for all agents using this server.

| Field | Required | Description |
|---|---|---|
| `tool_name` | Yes | Exact tool name from `tools/list` (case-sensitive, min 1 char). |
| `message` | No | Approval prompt. Supports `{{args.field}}` and `{{tool_name}}` placeholders. If empty: auto-generates "Execute tool: {tool_name}". |

### Message Template Syntax

| Placeholder | Source | Behavior |
|---|---|---|
| `{{args.field_name}}` | Tool call arguments | Replaced with value; missing args become `<unknown>` |
| `{{tool_name}}` | Tool name | Always available |

Guidelines: be specific, use action verbs, include highest-risk arguments, keep under 100 characters.

## Default Enabled Tools (`default_enabled_tools`)

Platform-level tool gate — the default set of tools available when agents reference this server.

- Empty list → all tools enabled by default
- Non-empty list → only listed tools are available; agents can restrict further but never expand
- Tool names must match exactly what the server reports via `tools/list`

## Placeholder Syntax Summary

| Syntax | Context | Resolved By | Example |
|---|---|---|---|
| `${VAR_NAME}` | HTTP headers, query_params | Agent runner from environment | `"Bearer ${API_TOKEN}"` |
| `{{args.field}}` | Approval messages | Approval engine from tool args | `"Delete: {{args.repo}}"` |

**Never mix these two syntaxes** — `${VAR_NAME}` is for environment variable injection, `{{args.field}}` is for approval message rendering.

```

### references/agent-integration.md

```markdown
# Agent Integration Reference

How agents reference McpServers, the tool approval policy chain, sub-agent access, and the full runtime resolution flow.

## McpServerUsage in Agent Spec

Agents declare MCP server usage via `spec.mcp_server_usages`:

```yaml
# In Agent spec
spec:
  mcp_server_usages:
    - mcp_server_ref:
        kind: mcp_server           # snake_case (NOT McpServer)
        slug: github               # matches McpServer metadata.slug
      enabled_tools:               # optional — subset of default_enabled_tools
        - search_code
        - get_file_contents
        - create_pull_request
      tool_approval_overrides:     # optional — per-agent customization
        - tool_name: delete_repository
          requires_approval: true
          message: "Delete repository: {{args.repo_name}}"
```

### McpServerUsage Fields

| Field | Required | Description |
|---|---|---|
| `mcp_server_ref` | Yes | Reference with `kind: mcp_server` and `slug`. Add `org` for cross-org references. |
| `enabled_tools` | No | Tools to enable. Empty = use McpServer's `default_enabled_tools` (or all if not set). Cannot expand beyond McpServer's gate. |
| `tool_approval_overrides` | No | Per-agent approval policy customization (see below). |

The `mcp_server_ref.slug` must be **unique** within a single agent's `mcp_server_usages`.

### Reference Format

```yaml
# Relative reference (recommended) — org resolved from agent's metadata.org
mcp_server_ref:
  kind: mcp_server
  slug: github

# Absolute reference — for cross-org or marketplace servers
mcp_server_ref:
  org: stigmer
  kind: mcp_server
  slug: github
```

Canonical format: `org/slug` (e.g., `stigmer/github`, `acme-corp/internal-db`).

## Three-Layer Approval Policy Chain

Approval policies resolve in order of increasing priority:

```
McpServer.default_tool_approvals          ← base layer (all agents)
        │
        ▼ overrides
Agent.McpServerUsage.tool_approval_overrides  ← per-agent layer
        │
        ▼ overrides
AgentExecution.auto_approve_all           ← runtime bypass
```

| Priority | Source | Scope |
|---|---|---|
| 1 (lowest) | `McpServer.default_tool_approvals` | All agents using this server |
| 2 | `Agent.tool_approval_overrides` | Single agent |
| 3 (highest) | `AgentExecution.auto_approve_all` | Single execution (runtime) |

### ToolApprovalOverride Fields

| Field | Required | Description |
|---|---|---|
| `tool_name` | Yes | Exact tool name (case-sensitive) |
| `requires_approval` | Yes | `true` = requires approval; `false` = no approval (overrides McpServer default) |
| `message` | No | Custom approval prompt. If empty: inherits McpServer message or auto-generates. |

### Override Examples

**Trusted agent — disable McpServer defaults:**
```yaml
tool_approval_overrides:
  - tool_name: delete_repository
    requires_approval: false
  - tool_name: force_push
    requires_approval: false
```

**Stricter agent — add approvals McpServer doesn't require:**
```yaml
tool_approval_overrides:
  - tool_name: send_email
    requires_approval: true
    message: "Send email to {{args.recipient}}: {{args.subject}}"
  - tool_name: create_ticket
    requires_approval: true
    message: "Create support ticket for customer"
```

## Sub-Agent MCP Access

Sub-agents can only access MCP servers the parent has in `mcp_server_usages`. Access is granted via `mcp_access`:

```yaml
sub_agents:
  - name: code-reviewer
    description: "Reviews code changes"
    instructions: "You review code changes for quality..."
    mcp_access:
      - mcp_server: github         # slug from parent's mcp_server_usages
        enabled_tools:             # subset of parent's enabled_tools
          - search_code
          - get_file
```

| McpAccess Field | Description |
|---|---|
| `mcp_server` | Slug matching `mcp_server_ref.slug` from parent's usages |
| `enabled_tools` | Tools for this sub-agent (subset of parent's). Empty = all parent tools. |

## Runtime Resolution Flow

1. **Agent** declares `mcp_server_usages` (references only — no secrets)
2. **AgentInstance** binds Agent to Environment (provides actual credential values)
3. **Agent Runner** resolves each McpServer ref, retrieves secrets from Environment, starts MCP server process
4. Tools become available during AgentExecution

The McpServer YAML is **portable and secret-free**. Different AgentInstances bind the same Agent to different environments (staging vs production).

## Post-Apply Workflow

```bash
# 1. Apply the McpServer
stigmer apply -f mcpserver.yaml

# 2. Discover tools (connects locally, pushes metadata to platform)
stigmer discover mcp-server <slug>

# 3. Verify discovered tools
stigmer get mcp-server <slug> --output yaml
# Check status.discovered_capabilities.tools[*].name

# 4. Use discovered names in default_enabled_tools, default_tool_approvals, and agent enabled_tools
```

Discovery runs on the developer's machine — credentials never leave the local environment. Only tool metadata (names, descriptions, schemas) is sent to the platform.

```

### references/validation.md

```markdown
# Validation Checklist

Run through this checklist before presenting any McpServer YAML. Every item must pass.

## Required Fields

- [ ] `apiVersion` is exactly `agentic.stigmer.ai/v1`
- [ ] `kind` is exactly `McpServer` (PascalCase — not `mcpserver`, `Mcpserver`, `mcp_server`, `MCP_SERVER`)
- [ ] `metadata.name` is present
- [ ] Exactly one of `spec.stdio` or `spec.http` is specified (proto `oneof` with `required` — omitting both or both present fails)
- [ ] `spec.description` is present and explains the server's purpose

## Stdio Servers

- [ ] `spec.stdio.command` is present
- [ ] Command is a real executable (`npx`, `python`, `node`, `./binary`, etc.)
- [ ] `working_dir` uses absolute path if specified
- [ ] All required env vars declared in `env_spec`

## HTTP Servers

- [ ] `spec.http.url` is a valid HTTP or HTTPS URL
- [ ] Every `${VAR_NAME}` in `headers` and `query_params` has a matching `env_spec.data` entry
- [ ] `timeout_seconds` is in range 0–300 if specified

## Metadata

- [ ] `slug` (if specified) matches `^[a-z][a-z0-9-]*$`, 1–63 characters
- [ ] `org` is set (auto-resolved from context if omitted, but recommended to be explicit)
- [ ] `visibility` is intentional — only `visibility_public` for marketplace servers

## Environment Variables

- [ ] Every env var has `is_secret` correctly classified
- [ ] Secret values are NOT pre-filled (no `value` field for secrets)
- [ ] Descriptions specify required permissions/format/scopes
- [ ] Non-secret shared defaults may optionally have `value` pre-filled

## Tool Names

- [ ] All names in `default_enabled_tools` are verified (not guessed)
- [ ] All `tool_name` in `default_tool_approvals` match exactly (case-sensitive)
- [ ] If tool names are unverified, include a note to run `stigmer discover mcp-server <slug>` after applying

## Placeholder Syntax

- [ ] HTTP headers/params use `${VAR_NAME}` (not `{{}}`)
- [ ] Approval messages use `{{args.field}}` (not `${}`)
- [ ] These two syntaxes are never mixed up

## Status

- [ ] No `status` fields set (system-managed — omit entirely or leave as `{}`)

## Common Pitfalls

### Wrong `kind` casing
```yaml
# WRONG                    # CORRECT
kind: mcpserver            kind: McpServer
kind: Mcpserver            kind: McpServer
kind: mcp_server           kind: McpServer
```

Note: In Agent `mcp_server_ref`, use `kind: mcp_server` (snake_case). In the McpServer resource itself, use `kind: McpServer` (PascalCase). Both are correct for their respective contexts.

### Wrong `apiVersion`
```yaml
# WRONG                         # CORRECT
apiVersion: stigmer.ai/v1       apiVersion: agentic.stigmer.ai/v1
apiVersion: agentic/v1          apiVersion: agentic.stigmer.ai/v1
apiVersion: v1                  apiVersion: agentic.stigmer.ai/v1
```

### Mixing placeholder syntaxes
```yaml
# WRONG — ${} in approval message
message: "Delete ${args.repo}"

# WRONG — {{}} in HTTP header
Authorization: "Bearer {{API_TOKEN}}"

# CORRECT
Authorization: "Bearer ${API_TOKEN}"     # env var in header
message: "Delete repository: {{args.repo}}"  # tool arg in approval
```

### Secret values in spec
```yaml
# WRONG
GITHUB_TOKEN:
  value: "ghp_realtoken123"    # Never put real secrets here
  is_secret: true

# CORRECT
GITHUB_TOKEN:
  description: "GitHub PAT with repo scope"
  is_secret: true
```

### Unverified tool names (silent failure)
Tool names in `default_tool_approvals` that don't match the server's `tools/list` are **silently ignored** — no error, no warning, no approval enforced. Always verify names via discovery or documentation.

### Slug format errors
```yaml
# WRONG
slug: GitHub             # uppercase
slug: github_mcp         # underscores
slug: 123-github         # starts with digit

# CORRECT
slug: github
slug: github-mcp
slug: my-db-server-v2
```

```

### references/examples.md

```markdown
# McpServer YAML Examples

Complete examples from minimal to marketplace-ready. All examples use valid field values.

## Minimal Stdio Server

```yaml
apiVersion: agentic.stigmer.ai/v1
kind: McpServer
metadata:
  name: github
spec:
  description: "GitHub MCP server for repository operations"
  stdio:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
```

## Stdio Server with Environment Variables

```yaml
apiVersion: agentic.stigmer.ai/v1
kind: McpServer
metadata:
  name: github
  tags:
    - git
    - vcs
spec:
  description: "GitHub MCP server for repository operations, code search, and PR management"
  icon_url: "https://github.githubassets.com/favicons/favicon.svg"
  stdio:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
  env_spec:
    data:
      GITHUB_TOKEN:
        description: "GitHub personal access token with repo and read:org scopes"
        is_secret: true
      GITHUB_OWNER:
        description: "Default GitHub organization or username (e.g., acme-corp)"
        is_secret: false
```

## Stdio Server with Tool Gates and Approval Policies

```yaml
apiVersion: agentic.stigmer.ai/v1
kind: McpServer
metadata:
  name: github
  org: acme-corp
  tags:
    - git
    - vcs
    - code-review
spec:
  description: "GitHub MCP server for repository operations and code management"
  icon_url: "https://github.githubassets.com/favicons/favicon.svg"
  stdio:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
  default_enabled_tools:
    - search_code
    - get_file_contents
    - list_issues
    - create_issue
    - create_pull_request
    - get_pull_request
    - merge_pull_request
  default_tool_approvals:
    - tool_name: merge_pull_request
      message: "Merge PR #{{args.pull_number}} in {{args.repo}}"
    - tool_name: delete_repository
      message: "Delete repository: {{args.repo}}"
    - tool_name: force_push
      message: "Force push to {{args.branch}} on {{args.repo}}"
  env_spec:
    data:
      GITHUB_TOKEN:
        description: "GitHub personal access token with repo, read:org, and admin:repo_hook scopes"
        is_secret: true
```

## Database Server with Restricted Defaults

```yaml
apiVersion: agentic.stigmer.ai/v1
kind: McpServer
metadata:
  name: postgres
  labels:
    category: database
  tags:
    - database
    - sql
    - postgresql
spec:
  description: "PostgreSQL MCP server for database queries and schema inspection"
  stdio:
    command: python
    args: ["-m", "mcp_server_postgres"]
  default_enabled_tools:
    - execute_query
    - list_tables
    - describe_table
    - list_schemas
  env_spec:
    data:
      POSTGRES_URL:
        description: "PostgreSQL connection URL (postgres://user:pass@host/db)"
        is_secret: true
```

## Python Module Server

```yaml
apiVersion: agentic.stigmer.ai/v1
kind: McpServer
metadata:
  name: sqlite
spec:
  description: "SQLite MCP server for local database queries"
  stdio:
    command: python
    args: ["-m", "mcp_server_sqlite", "--db-path", "/data/db.sqlite"]
```

## HTTP Server with Header Authentication

```yaml
apiVersion: agentic.stigmer.ai/v1
kind: McpServer
metadata:
  name: web-search
  tags:
    - search
    - web
spec:
  description: "Web search MCP service for full-text search and page retrieval"
  http:
    url: "https://mcp.example.com/search/v1"
    headers:
      Authorization: "Bearer ${SEARCH_API_TOKEN}"
      X-API-Version: "2024-01"
    timeout_seconds: 45
  env_spec:
    data:
      SEARCH_API_TOKEN:
        description: "API token for the web search service"
        is_secret: true
```

## HTTP Server with Multi-Tenant Routing

```yaml
apiVersion: agentic.stigmer.ai/v1
kind: McpServer
metadata:
  name: internal-knowledge-base
  org: acme-corp
  visibility: visibility_private
  labels:
    category: knowledge
spec:
  description: "Internal knowledge base MCP server for policy and procedure lookup"
  http:
    url: "https://api.acme-corp.com/mcp/kb"
    headers:
      Authorization: "Bearer ${KB_SERVICE_TOKEN}"
      X-Tenant-ID: "${TENANT_ID}"
    query_params:
      version: "v2"
    timeout_seconds: 30
  default_tool_approvals:
    - tool_name: create_article
      message: "Create knowledge base article: {{args.title}}"
    - tool_name: delete_article
      message: "Delete article '{{args.title}}' (id: {{args.article_id}})"
  env_spec:
    data:
      KB_SERVICE_TOKEN:
        description: "Service token for the knowledge base API"
        is_secret: true
      TENANT_ID:
        description: "Tenant identifier for request routing (e.g., acme-corp)"
        is_secret: false
```

## Public Marketplace Server (Full-Featured)

```yaml
apiVersion: agentic.stigmer.ai/v1
kind: McpServer
metadata:
  name: Slack
  org: stigmer
  visibility: visibility_public
  labels:
    category: communication
    tier: production
  annotations:
    docs-url: "https://github.com/modelcontextprotocol/servers/tree/main/src/slack"
    support-url: "https://github.com/stigmer/stigmer/issues"
  tags:
    - slack
    - messaging
    - communication
spec:
  description: "Slack MCP server for channel messaging, search, and workspace management"
  icon_url: "https://a.slack-edge.com/80588/marketing/img/icons/icon_slack_hash_colored.png"
  tags:
    - slack
    - messaging
  stdio:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-slack"]
  default_enabled_tools:
    - list_channels
    - post_message
    - reply_to_thread
    - get_channel_history
    - search_messages
    - add_reaction
  default_tool_approvals:
    - tool_name: post_message
      message: "Post to #{{args.channel_name}}: {{args.text}}"
    - tool_name: reply_to_thread
      message: "Reply in #{{args.channel_name}} thread: {{args.text}}"
    - tool_name: invite_user_to_channel
      message: "Invite {{args.user_id}} to #{{args.channel_name}}"
    - tool_name: archive_channel
      message: "Archive channel #{{args.channel_name}}"
  env_spec:
    data:
      SLACK_BOT_TOKEN:
        description: "Slack Bot User OAuth Token (xoxb-...) with channels:read, chat:write, search:read scopes"
        is_secret: true
      SLACK_TEAM_ID:
        description: "Slack workspace team ID (e.g., T01234567)"
        is_secret: false
```

Marketplace characteristics:
- `metadata.org` set to the publishing organization
- `metadata.visibility: visibility_public` — any org can reference it
- `metadata.annotations` include support/documentation URLs
- `env_spec` descriptions precise enough for external users

```