URI Schemes & Addressing

Every MCP resource is identified by a URI. The scheme — file://, https://, postgres://, or a custom prefix — tells the client what kind of data source it is addressing and which server can resolve it. This is not arbitrary naming. The URI is the contract between the client and server: it encodes the data source type, the path to the specific resource, and optionally query parameters that shape the response. A well-designed URI scheme makes resources discoverable, predictable, and composable.

MCP supports three categories of URI schemes. Standard schemes (file://, https://) map to well-known protocols and behave exactly as you would expect — file:///var/log/app.log reads a file, https://api.example.com/users fetches an HTTP resource. Database schemes (postgres://, mysql://, sqlite://) address database objects like tables, views, or query results. Custom schemes (jira://, salesforce://, internal://) let you create domain-specific addressing for proprietary systems. The server declares which schemes it handles during capability negotiation, and the client routes requests accordingly.

URI templates add a dynamic layer. Instead of listing every possible resource statically, a server can advertise a template like users://{user_id}/profile and let the client fill in the parameter at runtime. This is essential for large datasets — you cannot enumerate every row in a database, but you can expose a template that addresses any row by its key. Templates follow RFC 6570 syntax, which supports simple substitution ({id}), path segments ({+path}), and query parameters ({?page,limit}).

// Standard scheme — file system
"file:///var/log/app.log"
"file:///etc/config/app.yaml"

// Standard scheme — HTTP
"https://api.example.com/v2/users"
"https://docs.internal.com/runbooks/deploy.md"

// Database scheme
"postgres://localhost/mydb/users"        // table
"postgres://localhost/mydb/query/active"  // named query
"sqlite:///data/analytics.db/events"     // SQLite table

// Custom scheme — domain-specific
"jira://PROJECT-123"                     // Jira issue
"salesforce://account/001xx000003DGbH"   // SF record
"s3://my-bucket/reports/2026-Q1.csv"     // S3 object

// URI template (RFC 6570)
"users://{user_id}/profile"              // simple sub
"logs://{service}/{+path}"               // path segment
"search://{query}{?page,limit}"          // query params

1. Inventory your data sources List every system the AI agent needs to read from — databases, file systems, APIs, SaaS tools. Each one is a candidate for a URI scheme.
2. Choose scheme types Use standard schemes (file://, https://) where they fit. Only create custom schemes for data sources that have no natural protocol mapping.
3. Design for discovery Implement resources/list so clients can enumerate available resources. Return both static URIs and URI templates so the client knows what is available and what is parameterized.