url_build

Construct a well-formed URL string from individual components. Useful when assembling a URL from values that come from separate sources such as configuration, templates, or user input.

Parameters

Parameter	Type	Required	Description
scheme	string	Yes	URL scheme (e.g. "https", "http", "ftp").
host	string	Yes	Hostname or IP address (e.g. "example.com", "192.168.1.1").
port	number	No	Port number to include in the URL. Omit to use the scheme default.
path	string	No	URL path (e.g. "/path/to/resource"). Defaults to "/" when omitted.
query	string	No	Raw query string without the leading ? (e.g. "key=value&other=x").
fragment	string	No	Fragment identifier without the leading # (e.g. "section").
username	string	No	Username for the authority component.
password	string	No	Password for the authority component. Requires username to be set.

Response

Field	Type	Description
url	string	The fully constructed URL string.

Examples

Input (full URL):

{
	"scheme": "https",
	"host": "api.example.com",
	"port": 8080,
	"path": "/v1/users",
	"query": "page=2&limit=10",
	"fragment": "results"
}

Result:

{
	"url": "https://api.example.com:8080/v1/users?page=2&limit=10#results"
}

---

Input (minimal):

{
	"scheme": "https",
	"host": "example.com"
}

Result:

{
	"url": "https://example.com/"
}

Errors

Each failure carries a precise code in the response. Argument-schema and server errors are JSON-RPC protocol errors; a rejected value is returned as a tool result with isError: true (so the agent can read the code and self-correct).

Code	When	Delivered as
invalid_arguments	An argument is missing or the wrong type.	protocol error (invalid_params)
invalid_url	The components do not form a valid URL — e.g. a malformed or unsupported scheme or host, a port or credentials that cannot be set on the URL, or password provided without username.	tool error (isError)
internal_error	An unexpected server error.	protocol error (internal_error)

Notes

• The query parameter is inserted verbatim — values are not percent-encoded automatically. Use url_encode first if individual parameter values may contain special characters.
• Providing password without username returns an invalid_url tool error.