Resources

Resources provide fast, local read-only data access through SQLite databases. Unlike tools that make HTTP requests to external APIs, resources query local .db files using sql.js (a pure JavaScript/WASM SQLite implementation). Resources are the second MCP primitive supported by FlowMCP v3.0.0.

Resources are optional. Most schemas only need tools. Add resources when your schema benefits from fast local data lookups that do not require network calls.

When to Use Resources

Use Case	Tool or Resource?
Fetch live data from an API	Tool
Look up static reference data (chain IDs, token lists)	Resource
Query historical data that changes infrequently	Resource
Perform calculations on cached data	Resource
Call external services	Tool

Resources are ideal for data that is bundled with the schema and updated only when the schema version changes.

Schema Format

Resources are declared in the resources key of the main export:

export const main = {
    namespace: 'etherscan',
    name: 'ContractExplorer',
    version: '3.0.0',
    root: 'https://api.etherscan.io',
    tools: { /* ... */ },
    resources: {
        verifiedContracts: {
            description: 'Lookup verified contracts by address or name',
            source: 'sqlite',
            database: 'contracts.db',
            queries: {
                byAddress: {
                    description: 'Find a verified contract by its address',
                    sql: 'SELECT name, compiler, optimization, source_code FROM contracts WHERE address = ?',
                    parameters: [
                        { key: 'address', type: 'string', description: 'Contract address (0x...)', required: true }
                    ]
                },
                byName: {
                    description: 'Search contracts by name pattern',
                    sql: 'SELECT address, name, compiler FROM contracts WHERE name LIKE ? LIMIT 20',
                    parameters: [
                        { key: 'pattern', type: 'string', description: 'Name search pattern (use % as wildcard)', required: true }
                    ]
                }
            }
        }
    }
}

Resource Fields

Field	Type	Required	Description
`description`	`string`	Yes	What data this resource provides. Visible to AI clients.
`source`	`string`	Yes	Must be `'sqlite'`. Only SQLite is supported in v3.0.0.
`database`	`string`	Yes	Path to the `.db` file, relative to the schema file. Must end in `.db`.
`queries`	`object`	Yes	Named queries with SQL and parameters. Max 4 queries per resource.

Query Fields

Each query is a named entry in the queries object:

Field	Type	Required	Description
`description`	`string`	Yes	What this query returns. Used by AI clients for query selection.
`sql`	`string`	Yes	SQL query string with `?` placeholders. Must start with `SELECT`.
`parameters`	`array`	No	Query parameters corresponding to `?` placeholders. Can be empty `[]`.
`tests`	`array`	No	Test cases with example parameter values.

Query Parameters

Resource query parameters use a simplified flat format (no position/z blocks):

parameters: [
    { key: 'address', type: 'string', description: 'Contract address', required: true },
    { key: 'limit', type: 'number', description: 'Max results', required: false }
]

Field	Type	Required	Description
`key`	`string`	Yes	Parameter name (camelCase). Maps to a `?` placeholder in order.
`type`	`string`	Yes	Must be `string`, `number`, or `boolean`.
`description`	`string`	Yes	What this parameter controls.
`required`	`boolean`	Yes	Whether the parameter must be provided.

The number of parameters must match the number of ? placeholders in the SQL query.

SQL Security Enforcement

Resources enforce strict read-only access. The following patterns are blocked at validation time:

Blocked Pattern	Reason
`INSERT`, `UPDATE`, `DELETE`, `DROP`	Write operations not allowed
`CREATE TABLE`, `ALTER TABLE`	Schema modifications not allowed
`ATTACH DATABASE`	Cross-database access not allowed
`LOAD_EXTENSION`	Extension loading not allowed
`PRAGMA` (most)	Configuration changes not allowed
String interpolation	All values must use `?` placeholders
Subqueries with writes	Nested write operations not allowed

// Valid — SELECT with prepared statement
sql: 'SELECT * FROM contracts WHERE address = ?'

// Valid — JOIN query
sql: 'SELECT c.name, t.symbol FROM contracts c JOIN tokens t ON c.token_id = t.id WHERE c.chain_id = ?'

// Invalid — not a SELECT statement
sql: 'INSERT INTO contracts VALUES (?)'

// Invalid — uses string interpolation instead of ?
sql: `SELECT * FROM contracts WHERE address = '${address}'`

// Invalid — blocked pattern
sql: 'ATTACH DATABASE "other.db" AS other'

All SQL queries must start with SELECT and use ? placeholders for all dynamic values. String interpolation, template literals, and concatenation in SQL strings are forbidden.

Runtime

Resources use sql.js, a pure JavaScript/WASM implementation of SQLite. This means:

No native dependencies — works on any platform that supports WASM
No SQLite installation required — everything is bundled
Read-only mode — databases are opened in read-only mode by default
Memory-safe — each query runs in an isolated context

Constraints

Constraint	Value	Rationale
Max resources per schema	2	Resources are supplementary, not primary output
Max queries per resource	4	Keeps resource scope focused
Source type	`sqlite` only	Future versions may add other sources
Database file extension	`.db`	Standard SQLite extension
SQL must start with	`SELECT`	Read-only enforcement
Parameter placeholders	`?` only	Prevents SQL injection
Parameter types	`string`, `number`, `boolean`	Simple types only

Complete Example

A schema with both tools and resources:

export const main = {
    namespace: 'etherscan',
    name: 'ContractExplorer',
    description: 'Explore Ethereum contracts via API and local database',
    version: '3.0.0',
    root: 'https://api.etherscan.io',
    requiredServerParams: [ 'ETHERSCAN_API_KEY' ],
    requiredLibraries: [],
    headers: {},
    tools: {
        getContractAbi: {
            method: 'GET',
            path: '/api',
            description: 'Fetch the ABI of a verified contract from the Etherscan API',
            parameters: [
                {
                    position: { key: 'module', value: 'contract', location: 'query' },
                    z: { primitive: 'string()', options: [] }
                },
                {
                    position: { key: 'action', value: 'getabi', location: 'query' },
                    z: { primitive: 'string()', options: [] }
                },
                {
                    position: { key: 'address', value: '{{USER_PARAM}}', location: 'query' },
                    z: { primitive: 'string()', options: [ 'min(42)', 'max(42)' ] }
                },
                {
                    position: { key: 'apikey', value: '{{SERVER_PARAM:ETHERSCAN_API_KEY}}', location: 'query' },
                    z: { primitive: 'string()', options: [] }
                }
            ]
        }
    },
    resources: {
        verifiedContracts: {
            description: 'Local database of verified contract metadata',
            source: 'sqlite',
            database: 'contracts.db',
            queries: {
                byAddress: {
                    description: 'Find contract by Ethereum address',
                    sql: 'SELECT name, compiler_version, optimization, license FROM contracts WHERE address = ?',
                    parameters: [
                        { key: 'address', type: 'string', description: 'Contract address (0x...)', required: true }
                    ],
                    tests: [
                        {
                            _description: 'USDC proxy contract',
                            address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
                        }
                    ]
                },
                recentlyVerified: {
                    description: 'List recently verified contracts',
                    sql: 'SELECT address, name, verified_at FROM contracts ORDER BY verified_at DESC LIMIT ?',
                    parameters: [
                        { key: 'limit', type: 'number', description: 'Number of contracts to return', required: true }
                    ]
                }
            }
        }
    }
}

This schema provides two ways to access contract data:

Tool (getContractAbi) — fetches live ABI data from the Etherscan API (requires network and API key)
Resource (verifiedContracts) — queries a local SQLite database of contract metadata (instant, no network, no API key)

The AI agent can choose the appropriate approach based on what data is needed.

Validation Rules

Resources are validated by rules RES001-RES023. Key rules include:

Code	Rule
RES003	Maximum 2 resources per schema
RES005	Source must be `'sqlite'`
RES006	Database path must end in `.db`
RES008	Maximum 4 queries per resource
RES012	SQL must start with `SELECT`
RES013	SQL must not contain blocked patterns
RES014	SQL must use `?` placeholders
RES015	Placeholder count must match parameter count

See Validation Rules for the complete list.

Getting Started

Specification v3.0.0

Guides

Ecosystem

Reference

When to Use Resources

Schema Format

Resource Fields

Query Fields

Query Parameters

SQL Security Enforcement

Runtime

Constraints

Complete Example

Validation Rules

Getting Started

Specification v3.0.0

Guides

Ecosystem

Reference

​When to Use Resources

​Schema Format

​Resource Fields

​Query Fields

​Query Parameters

​SQL Security Enforcement

​Runtime

​Constraints

​Complete Example

​Validation Rules

When to Use Resources

Schema Format

Resource Fields

Query Fields

Query Parameters

SQL Security Enforcement

Runtime

Constraints

Complete Example

Validation Rules