feat: support .mcp.json for MCP server configuration #1481

neubig · 2025-12-22T16:11:18Z

Summary

This PR adds support for .mcp.json files in AgentSkills directories (SKILL.md format), following the AgentSkills standard for MCP server configuration.

NOTE: until 1480 is merged, read the diff below instead of the "files changed" tab.

Based on PR #1480 (SKILL.md convention support) - View diff from #1480

Changes

MCP Loading Rules

AgentSkills (SKILL.md directories): ONLY load .mcp.json files, ignore mcp_tools frontmatter
Legacy skills (.md files): ONLY load mcp_tools from frontmatter, no .mcp.json support

New Private Functions

_find_mcp_config() - Locates .mcp.json files in a skill directory
_expand_mcp_variables() - Expands variables in MCP configuration:
- ${VAR} - Environment variable or provided variable
- ${VAR:-default} - With default value if not found
- ${SKILL_ROOT} - Automatically set to the skill directory path
_load_mcp_config() - Loads and validates .mcp.json files

Example `.mcp.json`

{
  "mcpServers": {
    "pdf-processor": {
      "command": "${SKILL_ROOT}/scripts/server.py",
      "args": ["--port", "${PORT:-8080}"]
    }
  }
}

Testing

Verified with a realistic test skill directory:

test-skills/
└── pdf-processor/
    ├── SKILL.md
    └── .mcp.json

Test output:

Skill name: pdf-processor
MCP tools loaded: True

MCP config:
{
  "mcpServers": {
    "pdf-processor": {
      "command": "/workspace/project/test-skills/pdf-processor/scripts/server.py",
      "args": ["--port", "8080"],
      "env": {"PYTHONPATH": "/workspace/project/test-skills/pdf-processor/lib"}
    }
  }
}

✓ ${SKILL_ROOT} was correctly expanded
✓ ${PORT:-8080} default value was correctly applied

Added 6 tests covering:

AgentSkills loading .mcp.json with variable expansion
AgentSkills ignoring mcp_tools frontmatter
Legacy skills loading mcp_tools from frontmatter
Legacy skills ignoring .mcp.json in directory
Invalid JSON error handling
load_skills_from_dir() with mixed skill types

Backward Compatibility

All changes are backward compatible
Existing legacy skills with mcp_tools frontmatter continue to work
.mcp.json is only loaded for AgentSkills (SKILL.md directory format)

Related Issues

Closes #1476

Part of #1473 (Support AgentSkills standard)

Agent Server images for this PR

• GHCR package: https://github.com/OpenHands/agent-sdk/pkgs/container/agent-server

Variants & Base Images

Variant	Architectures	Base Image	Docs / Tags
java	amd64, arm64	`eclipse-temurin:17-jdk`	Link
python	amd64, arm64	`nikolaik/python-nodejs:python3.12-nodejs22`	Link
golang	amd64, arm64	`golang:1.21-bookworm`	Link

Pull (multi-arch manifest)

# Each variant is a multi-arch manifest supporting both amd64 and arm64
docker pull ghcr.io/openhands/agent-server:9669acc-python

Run

docker run -it --rm \
  -p 8000:8000 \
  --name agent-server-9669acc-python \
  ghcr.io/openhands/agent-server:9669acc-python

All tags pushed for this build

ghcr.io/openhands/agent-server:9669acc-golang-amd64
ghcr.io/openhands/agent-server:9669acc-golang_tag_1.21-bookworm-amd64
ghcr.io/openhands/agent-server:9669acc-golang-arm64
ghcr.io/openhands/agent-server:9669acc-golang_tag_1.21-bookworm-arm64
ghcr.io/openhands/agent-server:9669acc-java-amd64
ghcr.io/openhands/agent-server:9669acc-eclipse-temurin_tag_17-jdk-amd64
ghcr.io/openhands/agent-server:9669acc-java-arm64
ghcr.io/openhands/agent-server:9669acc-eclipse-temurin_tag_17-jdk-arm64
ghcr.io/openhands/agent-server:9669acc-python-amd64
ghcr.io/openhands/agent-server:9669acc-nikolaik_s_python-nodejs_tag_python3.12-nodejs22-amd64
ghcr.io/openhands/agent-server:9669acc-python-arm64
ghcr.io/openhands/agent-server:9669acc-nikolaik_s_python-nodejs_tag_python3.12-nodejs22-arm64
ghcr.io/openhands/agent-server:9669acc-golang
ghcr.io/openhands/agent-server:9669acc-java
ghcr.io/openhands/agent-server:9669acc-python

About Multi-Architecture Support

Each variant tag (e.g., 9669acc-python) is a multi-arch manifest supporting both amd64 and arm64
Docker automatically pulls the correct architecture for your platform
Individual architecture tags (e.g., 9669acc-python-amd64) are also available if needed

Add support for AgentSkills standard fields (https://agentskills.io/specification): - description: Brief description of what the skill does - license: License under which the skill is distributed - compatibility: Environment requirements or compatibility notes - metadata: Arbitrary key-value metadata for extensibility - allowed_tools: List of pre-approved tools for the skill Also adds skills-ref as an optional dependency for future validation and prompt generation utilities. Closes #1474 Co-authored-by: openhands <openhands@all-hands.dev>

The skills-ref library will be added when validation and prompt generation utilities are implemented (issue #1478). Co-authored-by: openhands <openhands@all-hands.dev>

- Add find_skill_md() function to locate SKILL.md files (case-insensitive) - Add validate_skill_name() function for AgentSkills spec validation - Update load_skills_from_dir() to support skill-name/SKILL.md directories - Add directory_name and validate_name parameters to Skill.load() - Export new functions from __init__.py - Add 27 unit tests for new functionality Closes #1475 Co-authored-by: openhands <openhands@all-hands.dev>

github-actions · 2025-12-22T16:13:57Z

Coverage Report •

File	Stmts	Miss	Cover	Missing
openhands-sdk/openhands/sdk/context/skills
skill.py	393	313	20%	130–136, 142–146, 152–159, 187, 189–190, 192–193, 195, 206, 208–211, 214, 217–219, 224–228, 230, 246–248, 251–252, 256, 258–261, 264, 267–269, 271, 295, 298, 306, 311–313, 319, 321–327, 330, 339–340, 349, 365, 367–368, 380–381, 386, 393, 403–404, 406, 412–413, 415, 424–427, 429–432, 440–442, 450–452, 464–469, 481–486, 507, 510, 512–514, 517–522, 524, 526–527, 546–552, 554–555, 560–562, 565, 568–571, 573, 586, 588–590, 592–593, 595–596, 601–602, 604, 619–620, 623, 625–628, 630–632, 637–639, 651–659, 672–681, 702, 706–710, 712, 735–736, 738–741, 744–748, 751–752, 757–758, 763–764, 768–769, 775, 796–797, 799–802, 804–806, 811–815, 817, 821–822, 824, 827, 845–846, 848–849, 852, 857–859, 862, 864–866, 871–875, 877, 882–883, 887, 890, 904–906, 924, 926–930, 937, 944–948, 953–955, 957, 972, 974, 976–980, 983–986, 1020, 1022, 1024–1025, 1027–1029, 1032–1035, 1038, 1040, 1043–1045, 1049–1055, 1057–1058, 1060, 1063
TOTAL	14501	6884	52%

Reduce test code while maintaining essential coverage. Co-authored-by: openhands <openhands@all-hands.dev>

openhands-ai · 2025-12-22T16:36:52Z

Looks like there are a few issues preventing this PR from being merged!

GitHub Actions are failing:
- Agent Server

If you'd like me to help, just leave a comment, like

@OpenHands please fix the failing actions on PR #1481 at branch `feat/mcp-json-support`

Feel free to include any additional details that might help me get this PR into a better state.

_{^{You can manage your notification settings}}

Resolved merge conflicts in: - openhands-sdk/openhands/sdk/context/skills/skill.py - tests/sdk/context/skill/test_agentskills_fields.py The resolution keeps both: 1. Pydantic field validators for allowed_tools and metadata from main 2. Skill name validation logic from this branch 3. SKILL.md convention support from this branch Co-authored-by: openhands <openhands@all-hands.dev>

Extract helper functions to simplify the load_skills_from_dir function: - _find_third_party_files: Find .cursorrules, AGENTS.md, etc. in repo root - _find_skill_md_directories: Find AgentSkills-style SKILL.md directories - _find_regular_md_files: Find regular .md files excluding SKILL.md dirs - _load_skill_safe: Load skills with consistent error handling This improves code readability and maintainability by following the single responsibility principle. Each helper function handles one specific aspect of skill discovery or loading. Co-authored-by: openhands <openhands@all-hands.dev>

Co-authored-by: openhands <openhands@all-hands.dev>

- Remove redundant tuple element from _find_skill_md_directories (directory_path can be derived from skill_md.parent) - Replace _load_skill_safe wrapper with _load_and_categorize that combines loading and categorization in one function - Auto-validate skill name when directory_name is provided (removed separate validate_name parameter) - Fix case-insensitive search for third-party files to iterate over all files instead of checking specific variants - Update tests to check for specific error messages instead of magic number assertions Co-authored-by: openhands <openhands@all-hands.dev>

SKILL.md directories should always be categorized as knowledge_skills (progressive loading), not repo_skills (permanent context), even when they have no triggers defined. This addresses enyst's feedback that AgentSkills are fundamentally different from permanent OH skills like repo.md - they should use progressive loading while permanent skills should use AGENTS.md. Changes: - Modified _load_and_categorize to always put SKILL.md files in knowledge_skills when directory_name is provided - Added test_skill_md_always_knowledge_skill to verify the behavior Co-authored-by: openhands <openhands@all-hands.dev>

The file_content parameter was only used in unit tests. Tests have been updated to use pytest's tmp_path fixture and write content to actual temp files instead. Co-authored-by: openhands <openhands@all-hands.dev>

…gacy formats Split load() into: - _load_agentskills_skill(): For SKILL.md files (AgentSkills format) - _load_legacy_openhands_skill(): For legacy OpenHands skill files - _create_skill_from_metadata(): Shared helper for Skill object creation Co-authored-by: openhands <openhands@all-hands.dev>

- load_skills_from_dir() now returns 3 dictionaries: repo_skills, knowledge_skills, agent_skills - AgentSkills (SKILL.md directories) are categorized into agent_skills (separate from OpenHands skills) - Updated all callers to handle the new return type - Updated tests to verify the new categorization This addresses enyst's review comment about keeping AgentSkills separate from OpenHands skills, as they follow different standards and loading patterns. Co-authored-by: openhands <openhands@all-hands.dev>

neubig · 2025-12-30T21:10:18Z

@OpenHands pull in the changes from #1480, re-do the PR description to say it is based on 1480, and only search for and load .mcp.json for agent_skills, not knowledge and repo skills.

openhands-ai · 2025-12-30T21:10:27Z

I'm on it! neubig can track my progress at all-hands.dev

openhands-ai · 2025-12-30T21:18:17Z

Summary

I've completed all the requested changes for PR #1481:

Checklist

✅ Pulled in changes from PR feat: support SKILL.md file convention and name validation #1480 - Reset branch to feat/skill-md-convention and built on top of it
✅ Merged main - Already up to date
✅ Modified code to only search/load .mcp.json for agent_skills - Legacy .md files (knowledge and repo skills) do NOT load .mcp.json
✅ Updated PR description - Now references PR feat: support SKILL.md file convention and name validation #1480 with a "show diff" link

Changes Made (1 commit on top of PR #1480)

Files modified:

openhands-sdk/openhands/sdk/context/skills/skill.py - Added helper functions and modified _load_agentskills_skill() to load .mcp.json
openhands-sdk/openhands/sdk/context/skills/__init__.py - Exported new functions
tests/sdk/context/skill/test_mcp_json.py - Added 17 tests

Key implementation details:

find_mcp_config() - Locates .mcp.json in skill directories
expand_mcp_variables() - Expands ${VAR} and ${VAR:-default} patterns
load_mcp_config() - Loads and validates .mcp.json files
mcp_config_path field added to Skill model
.mcp.json is only loaded for agent_skills (SKILL.md directories), NOT for knowledge or repo skills

All 91 tests pass. PR updated at: #1481

View full conversation

Add support for .mcp.json files in AgentSkills directories (SKILL.md format), following the AgentSkills standard for MCP server configuration. Changes: - Add _find_mcp_config() to locate .mcp.json files in skill directories - Add _expand_mcp_variables() for variable expansion (${VAR}, ${VAR:-default}) - Add _load_mcp_config() to load and validate .mcp.json files - Update _load_agentskills_skill() to load .mcp.json (agent_skills only) - Update _load_legacy_openhands_skill() to load mcp_tools from frontmatter MCP loading rules: - AgentSkills (SKILL.md): ONLY use .mcp.json, ignore mcp_tools frontmatter - Legacy skills (.md): ONLY use mcp_tools frontmatter, no .mcp.json support Co-authored-by: openhands <openhands@all-hands.dev>

neubig · 2025-12-31T13:17:56Z

@OpenHands resolve merge conflicts with main, favoring the changes made on main

openhands-ai · 2025-12-31T13:18:05Z

I'm on it! neubig can track my progress at all-hands.dev

Resolved merge conflicts by keeping the .mcp.json loading functionality from this branch while incorporating main's changes (PR #1480). Key changes preserved: - AgentSkills (SKILL.md) load .mcp.json with variable expansion - Legacy skills load mcp_tools from frontmatter only - _find_mcp_config, _expand_mcp_variables, _load_mcp_config functions Co-authored-by: openhands <openhands@all-hands.dev>

Use directory_name consistently as in main branch. Co-authored-by: openhands <openhands@all-hands.dev>

enyst · 2025-12-31T15:54:40Z

openhands-sdk/openhands/sdk/context/skills/skill.py


-        return cls._create_skill_from_metadata(agent_name, content, path, metadata_dict)
+        # Load MCP configuration from .mcp.json (agent_skills ONLY use .mcp.json)
+        mcp_tools: dict | None = None


Do we have any mcp_tools here?

we are here in the method loading AgentSkills

while it seems that mcp_tools is a field in "repo.md" -type Skills?

software-agent-sdk/openhands-sdk/openhands/sdk/context/skills/skill.py

Line 287 in 9e20a39

if not isinstance(mcp_tools, dict | None):

openhands-agent added 3 commits December 22, 2025 15:55

chore: remove unused agentskills optional dependency

c033966

The skills-ref library will be added when validation and prompt generation utilities are implemented (issue #1478). Co-authored-by: openhands <openhands@all-hands.dev>

neubig mentioned this pull request Dec 22, 2025

feat: support resource directories (scripts/, references/, assets/) #1482

Draft

refactor: consolidate AgentSkills tests

b5e571f

Reduce test code while maintaining essential coverage. Co-authored-by: openhands <openhands@all-hands.dev>

openhands-agent and others added 11 commits December 22, 2025 21:55

Merge main into feat/skill-md-convention

b33afe8

Co-authored-by: openhands <openhands@all-hands.dev>

Merge branch 'main' into feat/skill-md-convention

5649c81

Update organization

feb7a2d

Remove file_content parameter from Skill.load()

e86afb8

The file_content parameter was only used in unit tests. Tests have been updated to use pytest's tmp_path fixture and write content to actual temp files instead. Co-authored-by: openhands <openhands@all-hands.dev>

Merge remote-tracking branch 'origin/main' into feat/skill-md-convention

821f5b5

neubig force-pushed the feat/mcp-json-support branch from b3345e4 to 1bc5f51 Compare December 30, 2025 21:16

neubig force-pushed the feat/mcp-json-support branch from 1bc5f51 to ffb6c6a Compare December 30, 2025 21:23

neubig force-pushed the feat/mcp-json-support branch from ffb6c6a to e22f6c5 Compare December 30, 2025 21:30

neubig marked this pull request as ready for review December 30, 2025 21:39

neubig requested review from enyst and xingyaoww December 30, 2025 21:51

neubig force-pushed the feat/mcp-json-support branch from 3191785 to bfc17a7 Compare December 31, 2025 13:49

OpenHands deleted a comment from openhands-ai bot Dec 31, 2025

fix: remove duplicate path.parent.name assignment

bba56fa

Use directory_name consistently as in main branch. Co-authored-by: openhands <openhands@all-hands.dev>

enyst reviewed Dec 31, 2025

View reviewed changes

neubig marked this pull request as draft January 1, 2026 14:39

Merge branch 'main' into feat/mcp-json-support

e0963ec

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: support .mcp.json for MCP server configuration #1481

feat: support .mcp.json for MCP server configuration #1481

Uh oh!

neubig commented Dec 22, 2025 •

edited by github-actions bot

Loading

Uh oh!

github-actions bot commented Dec 22, 2025 •

edited

Loading

Uh oh!

openhands-ai bot commented Dec 22, 2025

Uh oh!

neubig commented Dec 30, 2025

Uh oh!

openhands-ai bot commented Dec 30, 2025

Uh oh!

openhands-ai bot commented Dec 30, 2025

Uh oh!

neubig commented Dec 31, 2025

Uh oh!

openhands-ai bot commented Dec 31, 2025

Uh oh!

enyst Dec 31, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

feat: support .mcp.json for MCP server configuration #1481

Are you sure you want to change the base?

feat: support .mcp.json for MCP server configuration #1481

Uh oh!

Conversation

neubig commented Dec 22, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

MCP Loading Rules

New Private Functions

Example .mcp.json

Testing

Backward Compatibility

Related Issues

Uh oh!

github-actions bot commented Dec 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openhands-ai bot commented Dec 22, 2025

Uh oh!

neubig commented Dec 30, 2025

Uh oh!

openhands-ai bot commented Dec 30, 2025

Uh oh!

openhands-ai bot commented Dec 30, 2025

Summary

Checklist

Changes Made (1 commit on top of PR #1480)

Uh oh!

neubig commented Dec 31, 2025

Uh oh!

openhands-ai bot commented Dec 31, 2025

Uh oh!

enyst Dec 31, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

neubig commented Dec 22, 2025 •

edited by github-actions bot

Loading

Example `.mcp.json`

github-actions bot commented Dec 22, 2025 •

edited

Loading