🔥AWS Strands can't read GitHub Files with MCP🔥

aka, Are you sure you don't want to accept my PR to fix this?

This blog series focuses on presenting complex DevOps projects as simple and approachable via plain language and lots of pictures. You can do it!

These articles are supported by readers, please consider subscribing to support me writing more of these articles <3 :)

Hey all!

I’ve been playing around with Strands a great deal, and having a ton of fun. Strands Agents is a python library that permits writing agentic workloads with relatively little code, and supports all sorts of AI backends to provide the AI services, including Amazon Bedrock, OpenAI, Anthropic, and even local models on your computer.

Here’s one that fetches vectors from an AWS Bedrock Knowledge Base, feeds those vectors into an Agent (by default Claude 4), and streams an answer to the provided question - all in 4 lines! That’s absolutely absurd, it’s so cool.

from strands import Agent
from strands_tools import retrieve
agent = Agent(tools=[retrieve])
agent("Tell me about the cloud platform team")

One of the powers of Strands is it easily integrates with MCPs - those tool integrations that permit your agent to interact with the platforms your business uses to do stuff. Strands can use MCPs to look at:

• Your tickets in Jira? Yep!

• Your outage information from PagerDuty? Yep!

• Your code on GitHub? Well, sorta

Because “Resources” aren’t built out yet, Strands agents can’t yet read the contents of files from GitHub.

Lets talk about what’s missing and how to fix it!

Wait, What are we talking about?

There’s a lot going on here, so it’s important to understand the players.

First, there are AI clients - these provide the AI services from a platform, for example AWS Bedrock or OpenAI. You generally get a token from these platforms, export the token into your terminal, and you can then use tools that trigger jobs on these platforms.

If you want to be fancy, you can say “requests for inference” instead of “jobs”. They have the same meaning.

Then there are MCP clients. These are the software components that can talk to MCP servers, potentially authenticate, and download the tools lists from the MCP server. Often this is your IDE like VSCode or Claude Code. Strands has an MCP client built in.

Then there are MCP servers. These can exist anywhere, but we’re seeing more and more of these as remote, first party MCP servers. That means the company who hosts the MCP server (remote to your client, like over the internet) is the place you’d use those tools. Think accessing a GitHub MCP from a GitHub URL in order to download tools to interact with GitHub’s codebase.

The platforms that store enterprise data have a great motivator to support MCP - all the enterprises that are charging into AI adoption can more easily consume those platforms if they can access an MCP for the platform. Early stage companies that are much more AI focused could easily use MCP availability as a primary differentiator when choosing which platforms to use.

The problem

So there’s a GitHub MCP! And it works great. When I first started working with it, I assumed it wasn’t completely implemented - it just entered General Availability (GA) Sept 4, 2025, and I was playing with it in Strands a few weeks before that.

It had this odd ability to read ALL the data from GitHub, but it couldn’t download file contents. Weird, but whatever.

However, when I tested the same GitHub MCP with VS Code IDE, it worked great.

So I tested it with Claude Code, worked great.

It turns out ONLY Strands has a problem downloading file content from GitHub when using MCP.

I dug into the problem with some logging and found this log:

2025-08-22 07:50:55,725 | INFO | Thread-1 (_background_task) | httpx | HTTP Request: POST https://api.githubcopilot.com/mcp/ "HTTP/1.1 200 OK"
# ...
2025-08-22 07:50:55,865 | DEBUG | MainThread | strands.tools.mcp.mcp_client | [Thread: MainThread, Session: 838664df-dafb-4a06-865e-91d618eb77f6] unhandled content type: EmbeddedResource - dropping content
2025-08-22 07:50:55,865 | DEBUG | MainThread | strands.tools.mcp.mcp_client | [Thread: MainThread, Session: 838664df-dafb-4a06-865e-91d618eb77f6] tool execution completed with status: success

There’s two interesting things going on here. When the Strands agent attempts to fetch file contents, it uses a tool called get_file_contents. This tool is just an MCP instruction to use “Get Repository Contents” API to fetch a file contents.

It reads the header to identify the type of file. If it starts with `application`, it decides that file is text/ascii-based. For example, a .tfvars file (terraform variables) is text based, and the header value gets:

< content-type: application/json; charset=utf-8

After deciding the content is text, the GitHub MCP (really the Get Repository Contents REST API call), returns a payload like this:

{
  "type": "resource",
  "resource": {
    "uri": "repo://orgName/repoName/contents/path/to/file.tfvars",
    "mimeType": "application/json; charset=utf-8",
    "text": "... (plain-text contents of the file) ..."
  }
}

The Strands library expects to see direct TextResourceContents (on .text property path) or BlobResourceContents (on .blob property path) like this:

{
  "text": "... (plain-text contents of the file) ..."
}

Since the GitHub MCP is adding extra information, the Strands library totally fails to interpret it, despite the path being super duper close, and the information being nearly the same.

How To Fix It

You can’t. Well, at least not easily. The problem is in how the Strands library is written - it doesn’t yet have support for EmbeddedResources, which is the whole “.resource” property path and syntax.

I’ve created a fixed version on this PR: https://github.com/strands-agents/sdk-python/pull/726

This fixes the behavior for many types of files that are text encoded from github, but doesn’t yet work for binary/blob type files. It does however work for these types of files:

"application/json",
"application/xml",
"application/javascript",
"application/x-yaml",
"application/yaml",
"application/xhtml+xml",

And you’d be surprised how many file types are covered with these!

Try it out: Copy my version (from the PR) of this file: src/strands/tools/mcp/mcp_client.py over your version, and watch how your Strands agent can now fetch file contents:

What’s Next?

The Strands maintainers are hoping to implement full support for Resources before implementing partial support, meaning that this functionality isn’t coming immediately. Implementing the full lifecycle support for Resources will take a bit longer.

I’ll continue asking to merge this in - I think being able to fetch file contents from GitHub is a huge functionality gap for Strands, and will be relatively blocking for us.

Potentially we’ll need to implement some static tools for our bots to use to fetch file contents from GitHub using REST. I

And I’ll be sure to write about it.

Thanks all! Good luck out there.
kyler