docs(server): guide agents to read resources by URI, not name

[Lothsahn]

I noticed that asking Claude to read editor state often caused it to get 404 errors and have to retry to generate the right URI. With these changes in place, Claude gets the call right on the first time, every time, which makes development faster.

Description

Add a "Reading resources" section to the FastMCP server instructions string. It states that resources are addressed by URI (slashes), never by name (underscores); that the exact URI should be taken from the client's resources/list rather than constructed from the name; and that payloads are wrapped under a top-level data object (field paths look like data.section.field).

Prevents the common naive failure where an agent turns a resource name into a URI (e.g. editor_state -> mcpforunity://editor_state) and 404s, and the matching failure of guessing a bare top-level field instead of the nested data.* path.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Refactoring (no functional changes)
• Test update

Changes Made

Updated instructions to the agent on how to use resource URIs

Compatibility / Package Source

• Unity version(s) tested: 6000.3.19f1
• Package source used (#beta, #main, tag, branch, or file:): #main
• Resolved commit hash from Packages/packages-lock.json (if using a Git package URL): 78ee541

Testing/Screenshots/Recordings

• Python tests (cd Server && uv run pytest tests/ -v)
• Unity EditMode tests
• Unity PlayMode tests
• Package import/compile check
• Not applicable (explain why in Additional Notes)

Text of Claude conversation:
"There are errors in the console. Please debug and solve these"

01:32 PM claude-opus-4-8
I'll start by checking the Unity console for the errors. Let me first pin the correct Unity instance for this project.

● readMcpResource(Read resource "mcpforunity://instances" from server "UnityMCP")
{
"contents": [
{
"uri": "mcpforunity://instances",
"mimeType": "text/plain",
"text": "{"success": true, "transport": "stdio", "instance_count": 2, "instances": [{"id": "xxx@e5746cd5", "name": "xxx", "path": "D:/work/xxx/Assets", "hash": "e5746cd5", "port": 6405, "status": "running", "last_heartbeat": "2026-07-05T17:32:40.083693+00:00", "unity_version": "6000.3.19f1", "project_scoped_tools": false}, {"id": "xxx2@586c3840", "name": "xxx2", "path": "D:/work/xxx2/Assets", "hash": "586c3840", "port": 6402, "status": "running", "last_heartbeat": "2026-07-05T17:32:39.927504+00:00", "unity_version": "6000.3.19f1", "project_scoped_tools": false}]}"
}
]
}

01:32 PM claude-opus-4-8
The instance for this project is xxx@e5746cd5 (path D:/work/xxx/Assets). Let me pin it and read the console.

● UnityMCP - Set Active Instance (MCP)(instance: "xxx@e5746cd5")
{
"success": true,
"message": "Active instance set to xxx@e5746cd5",
"data": {
"instance": "xxx@e5746cd5",
"session_key": "global"
}
}

● UnityMCP - Read Console (MCP)(action: "get", types: ["error"], count: 50, include_stacktrace: true, format: "detailed")
{"success":true,"message":"Retrieved 50 log entries."

Documentation Updates

• I have added/removed/modified tools or resources
• If yes, I have updated all documentation files using:
  • The LLM prompt at tools/UPDATE_DOCS_PROMPT.md (recommended)
  • Manual review of the generated changes

Related Issues

None

Additional Notes

Feel free to reach out to me if you have any questions or concerns. Code changes were AI generated by Claude but I personally have reviewed, tested, and vouch for them (aka: not slop)

Summary by CodeRabbit

• Documentation
  • Clarified server guidance for working with resources.
  • Added instructions to use resource URIs from the resource list rather than resource names.
  • Noted that payload fields are available under a top-level data object for easier field access.

[coderabbitai]

📝 Walkthrough

Walkthrough

Updated the generated server instructions text to clarify resource-reading guidance: resources must be addressed by URI (not name), URIs should come from resources/list, and payload fields are nested under a top-level data object.

Changes

Instructions text update

Layer / File(s)	Summary
Resource-reading guidance Server/src/main.py	Added instructions clarifying resources are addressed by URI, URIs come from resources/list, and payload fields are under a top-level data object.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Possibly related issues

• Document resource-read server names for mcpforunity://custom-tools and instances in Codex clients #1220: Updates resource-read instructions to clarify how clients should discover and use the correct resource URI, similar to this PR's changes.

Possibly related PRs

• CoplayDev/unity-mcp#345: Both PRs adjust the server's MCP instruction/guidance text used to direct client behavior.

Suggested reviewers: msanatan

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the main change: guiding agents to read resources by URI instead of name.
Description check	✅ Passed	The description covers the required template sections and provides enough implementation, testing, and compatibility detail.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}