An agent’s document tool should fetch one document from an internal API. Its adapter has a configured base URL, checks that the host is approved, then joins that base with an argument supplied by the agent. The resulting request can point at a different host.
I would remove the URL argument from this tool. Let the agent supply a document ID; let the adapter own the route. Where an adapter genuinely needs URL input, evaluate the complete constructed destination before dispatch. Approving the base string earlier in the function leaves the caller in control of a later security decision.
This is a constructed Python example, not a reported incident in Claude Code or an MCP implementation. The downloadable fixture opens no network connections. It demonstrates URL composition and local validation, not a complete defence against server-side request forgery (SSRF).
A successful base check can precede a different host
Python’s urljoin documentation explicitly warns against using an attacker-controlled second argument. An absolute URL can replace the base. An argument beginning with // can replace its network location while retaining the scheme.
Consider this adapter shape. The names stand in for an application’s policy check and HTTP client:
require_origin(base)
url = urljoin(base, document_argument)
# The adapter would send its request to url here.
With these inputs, the earlier check says nothing about the new host:
base = "https://docs.example/v1/documents/"
document_argument = "//other.example/collect"
url = urljoin(base, document_argument)
# https://other.example/collect
The application constructs the different destination before the HTTP client runs, without a redirect or a changed DNS response. A credential attached later by the adapter could accompany that request, depending on how the adapter and client apply credentials. Even a request without credentials can disclose sensitive arguments or reach a destination the tool was never meant to contact.
The name document_argument does not restrict its contents. A tool schema that calls the field a string is also insufficient. The adapter needs an enforceable contract for which strings it accepts.
Run the composition failure locally
Download and inspect agent-url-construction.py, then run it with Python 3.9 or later:
python3 agent-url-construction.py
python3 agent-url-construction.py --test
python3 -O agent-url-construction.py --test
The demonstration prints:
{
"base_check": "allow",
"joined_url": "https://other.example/collect",
"final_origin_check": "deny",
"constructed_document_url": "https://docs.example/v1/documents/doc_42"
}
Both hosts are examples. The function checks strings and returns a decision; it does not attempt to fetch either address. Eight tests passed locally, both normally and with Python optimisation. The suite uses unittest checks, so optimisation does not remove its assertions.
The tests distinguish an absolute URL replacement from a // replacement. They also include a same-origin route change, invalid document IDs, misleading hostname prefixes, user information and unexpected ports. These cases are regression fixtures for the stated contract. They are not evidence that every URL parser, HTTP library or proxy interprets unusual input identically.
Give the tool a smaller input language
The repaired teaching function accepts an opaque ID with this application-owned grammar:
DOCUMENT_ID = re.compile(
r"[A-Za-z0-9][A-Za-z0-9_-]{0,63}", re.ASCII
)
The ID starts with an ASCII letter or digit and contains at most 64 characters. Later characters may also be underscores or hyphens. The function uses fullmatch, rejecting slashes, percent escapes, whitespace, query strings and fragments. It rejects non-string values before applying the pattern.
Those restrictions fit the invented document service in the example. They are not a universal rule for document identifiers. If your real API permits a different format, derive the accepted grammar from that API and test its encoding rules explicitly. Do not paste this pattern over a UUID, Unicode key or existing composite identifier without checking compatibility.
After validating the ID, the adapter constructs the destination from fixed components:
result = urlunsplit((
"https",
"docs.example",
"/v1/documents/" + document_id,
"",
"",
))
return require_origin(result)
The caller cannot select a scheme, authority or route. The final origin check remains as a defensive check on what the constructor returns. In this fixture, it requires HTTPS, the exact parsed hostname docs.example, and either no explicit port or port 443. It rejects user information and nonempty fragments, as well as whitespace and control characters before parsing. An invalid port raises an error, which must also stop dispatch.
The Python URL parsing security notes explain why parsing alone is insufficient: urlsplit and urlparse do not validate their inputs. Inspecting the parsed components is part of the policy. A raw prefix comparison such as url.startswith("https://docs.example") would accept https://docs.example.other.example/. The fixture rejects that host.
An approved origin still contains unauthorised routes
Moving the origin check after urljoin closes the cross-origin example. It does not constrain the path:
candidate = urljoin(BASE, "/admin/export")
require_origin(candidate) # Passes: the origin is unchanged.
The suite deliberately expects that pass. A same-origin destination can still name a route outside this document tool’s purpose. The narrow constructor rejects /admin/export as an ID and always emits the fixed document route instead.
Document-level permission remains another check. A well-formed doc_42 can identify a document the current user must not read. The receiving service must authorise that principal against the requested document, including its tenant. Neither the regex nor the origin check makes that access decision. The earlier article on authorisation during RAG neighbour expansion covers the same need to reapply access rules when a retrieval step introduces another document.
If the service supports several operations, expose explicit operations with separate input contracts. A read_document(document_id) tool is easier to constrain than a generic fetch(path) tool with access to every route on the host. That design also makes denied-operation tests easier to specify: the caller cannot turn a read into an export by supplying a different path.
Keep transport checks after the constructor
An approved URL is still only the start of the network operation. The OWASP SSRF prevention cheat sheet recommends disabling automatic redirection to prevent input-validation bypasses. It also describes DNS risks and the need for network controls. The fixture implements neither an HTTP redirect policy nor DNS and connection enforcement.
For the real adapter, configure the HTTP client to reject redirects unless there is a separately reviewed requirement for them. Keep TLS verification enabled. Apply the platform’s egress policy to the actual connection, and scope service credentials to the intended recipient. A string allowlist cannot establish which address a resolver returns or which peer a proxy contacts.
The earlier MCP transport-binding article addresses those later boundaries. Today’s failure is earlier and independently testable: composition changes the host before transport begins.
Before adopting this pattern, test your actual adapter with a disposable receiving service you control. Record the request target observed by that service, use dummy credentials, and exercise the client’s redirect settings. Confirm that invalid document arguments never reach the client’s send method. Keep those adapter tests separate from this offline fixture so a passing string test cannot be mistaken for verified network enforcement.
For the broader production approach to tool permissions and review, see my Claude Code book.