Skip to main content

MCP Server Specifications

MCP (Model Context Protocol) server specifications define how agents connect to external tools and services.

Overview​

MCP servers provide tools and resources to agents through a standardized protocol. Each specification defines the command to run, arguments, environment variables, and transport method.

Required Fields​

id (string)​

Unique identifier (kebab-case, e.g., kaggle, github, filesystem)

version (string)​

Spec version (currently 0.0.1).

name (string)​

Display name shown in the UI

description (string)​

Server capabilities description

command (string)​

Executable command to start the server

command: python
command: npx
command: node

args (list of strings)​

Command arguments including environment variable references

args:
  - "-m"
  - "mcp_remote"
  - "--Authorization"
  - "Bearer ${KAGGLE_TOKEN}"

Optional Fields​

transport (string)​

Transport protocol ("stdio" or "remote")

transport: stdio   # Standard input/output
transport: remote  # Remote HTTP connection

envvars (list of strings)​

Required environment variable IDs. References specs in envvars/ directory.

envvars:
  - KAGGLE_TOKEN:0.0.1
  - GITHUB_TOKEN

env (object)​

Environment variables to set for the server process

env:
  NODE_ENV: production
  LOG_LEVEL: info

tags (list of strings)​

Categorization tags

tags:
  - data
  - kaggle
  - datasets

icon (string)​

UI icon identifier

emoji (string)​

UI emoji identifier

Environment Variable Expansion​

Use ${VAR_NAME} syntax in args for environment variable expansion:

args:
  - "-m"
  - "mcp_remote"
  - "--Authorization"
  - "Bearer ${KAGGLE_TOKEN}"
  - "--accept"
  - "application/json"
  - "--"
  - "https://mcp.kaggle.com"

envvars:
  - KAGGLE_TOKEN

The ${KAGGLE_TOKEN} will be expanded at runtime by consuming systems.

Complete Example​

# Copyright (c) 2025-2026 Datalayer, Inc.
# Distributed under the terms of the Modified BSD License.

id: kaggle
version: 0.0.1
name: Kaggle MCP Server
description: Access Kaggle datasets, competitions, and kernels

command: python
args:
  - "-m"
  - "mcp_remote"
  - "--Authorization"
  - "Bearer ${KAGGLE_TOKEN}"
  - "--accept"
  - "application/json"
  - "--"
  - "https://mcp.kaggle.com"

transport: remote

envvars:
  - KAGGLE_TOKEN:0.0.1

tags:
  - data
  - kaggle
  - datasets

MCP Server Hierarchy​

MCP Server Specification
├── Basic Info (id, name, description, tags)
├── Execution (command, args, transport)
├── Environment
│   ├── envvars (required environment variables)
│   └── env (variables to set for the process)
└── UI (icon, emoji)

Available MCP Servers​

The following MCP servers are defined in agentspecs/mcp-servers/:

  • tavily - Web search via Tavily API
  • filesystem - Local filesystem operations
  • github - GitHub repository operations
  • google-workspace - Google Workspace integration
  • slack - Slack messaging
  • kaggle - Kaggle datasets and competitions
  • alphavantage - Financial market data
  • chart - Chart generation

Best Practices​

  1. ID Format: Use kebab-case (kaggle, not Kaggle or kaggle_mcp)
  2. Command: Use full command names (python, not py)
  3. Args: Break arguments into separate list items for clarity
  4. Environment Variables: Always define required envvars in the envvars field
  5. Variable Expansion: Use ${VAR_NAME} syntax consistently
  6. Transport: Specify stdio for local processes, remote for HTTP connections
  7. Tags: Use consistent tags for better categorization
  8. Description: Be specific about what tools and resources the server provides

Full Field Coverage​

Required fields:

  • id
  • version
  • name
  • description
  • command
  • args

Common optional fields:

  • transport (stdio or remote)
  • envvars (prefer versioned refs)
  • env (process env injection)
  • tags
  • icon, emoji