​
Overview

The @atxp/sqlite package provides a SQLite-based OAuth database implementation for ATXP. It offers persistent OAuth token storage using SQLite, ensuring data retention across application restarts.
This package is designed to work seamlessly with @atxp/client and @atxp/express packages when you need persistent storage that survives application restarts. For high-scale applications, consider using @atxp/redis instead.

​
Installation

npm install @atxp/sqlite
The @atxp/sqlite package includes TypeScript definitions and requires Node.js 16 or higher. It automatically installs @atxp/common as a dependency.

​
API Reference

​
Classes

​
SQLiteOAuthDatabase

The main class for managing OAuth tokens in a SQLite database. 
import { SQLiteOAuthDatabase } from '@atxp/sqlite'
Constructor 
new SQLiteOAuthDatabase(options: SQLiteOAuthDatabaseOptions)
​
options
SQLiteOAuthDatabaseOptions
required
Configuration options for the SQLite database connection.
Methods
​
saveAccessToken
Promise<void>
Saves an OAuth access token in the database.
​
getAccessToken
Promise<AccessToken | null>
Retrieves an OAuth access token from the database.
​
deleteToken
Promise<boolean>
Deletes an OAuth token from the database.
​
key
string
required
Unique identifier for the token to delete.
​
hasToken
Promise<boolean>
Checks if a token exists in the database.
​
key
string
required
Unique identifier for the token to check.
​
listTokens
Promise<string[]>
Lists all token keys stored in the database.
​
close
Promise<void>
Closes the database connection and releases resources.

​
Interfaces

​
SQLiteOAuthDatabaseOptions

Configuration options for the SQLite OAuth database. 
interface SQLiteOAuthDatabaseOptions {
  databasePath: string
  autoCreateTables?: boolean
  connectionTimeout?: number
}
​
databasePath
string
required
Path to the SQLite database file. Can be a relative or absolute path.
​
autoCreateTables
boolean
default:"true"
Whether to automatically create the required database tables on initialization.
​
connectionTimeout
number
default:"5000"
Connection timeout in milliseconds.

​
Usage Examples

​
Integration with ATXP Client

Use SQLite storage with the ATXP client for persistent token management: 
import { atxpClient, ATXPAccount } from '@atxp/client'
import { SQLiteOAuthDatabase } from '@atxp/sqlite'

// Create OAuth database
const oauthDb = new SQLiteOAuthDatabase({
  databasePath: './atxp-tokens.db'
})

// Create ATXP client with custom OAuth storage
const client = await atxpClient({
  mcpServer: 'https://browse.mcp.atxp.ai/',
  account: new ATXPAccount(process.env.ATXP_CONNECTION),
  oauthDatabase: oauthDb
})

// Use the client - tokens will be automatically stored in SQLite
const result = await client.callTool('browse', {
  url: 'https://example.com'
})

​
Integration with ATXP Server

Use SQLite storage with the ATXP server for persistent session management: 
import { atxpExpress, ATXPPaymentDestination } from '@atxp/express'
import { SQLiteOAuthDatabase } from '@atxp/sqlite'
import express from 'express'

// Create OAuth database
const oauthDb = new SQLiteOAuthDatabase({
  databasePath: './server-tokens.db'
})

const app = express()

// Use ATXP server with SQLite OAuth storage
app.use('/mcp', atxpExpress({
  paymentDestination: new ATXPPaymentDestination(process.env.ATXP_CONNECTION),
  payeeName: 'My MCP Server',
  oauthDatabase: oauthDb
}))

app.listen(3000, () => {
  console.log('Server running on port 3000')
})

​
Configuration

​
Database File Location

The SQLite database file can be placed anywhere on your filesystem: 
// Relative path (creates file in current directory)
const oauthDb = new SQLiteOAuthDatabase({
  databasePath: './tokens.db'
})

// Absolute path
const oauthDb = new SQLiteOAuthDatabase({
  databasePath: '/var/lib/atxp/tokens.db'
})

// In-memory database (temporary, not persistent)
const oauthDb = new SQLiteOAuthDatabase({
  databasePath: ':memory:'
})

​
Environment Variables

Configure the database path using environment variables: 
# .env file
ATXP_SQLITE_DB_PATH=./oauth-tokens.db
ATXP_SQLITE_CONNECTION_TIMEOUT=10000

import { SQLiteOAuthDatabase } from '@atxp/sqlite'

const oauthDb = new SQLiteOAuthDatabase({
  databasePath: process.env.ATXP_SQLITE_DB_PATH || './tokens.db',
  connectionTimeout: parseInt(process.env.ATXP_SQLITE_CONNECTION_TIMEOUT || '5000')
})

​
Database Schema

The package automatically creates the following table structure: 
CREATE TABLE oauth_tokens (
  key TEXT PRIMARY KEY,
  token TEXT NOT NULL,
  expires_at INTEGER,
  created_at INTEGER DEFAULT (strftime('%s', 'now')),
  updated_at INTEGER DEFAULT (strftime('%s', 'now'))
)
The database schema is automatically created when autoCreateTables is set to true (default). You can disable this behavior if you want to manage the schema manually.

​
Troubleshooting

​
Common Issues

If you encounter permission errors when creating or accessing the database file:
  • Ensure the directory exists and has write permissions
  • Check that the user running the application has access to the database path
  • Consider using an absolute path instead of a relative path
// Use absolute path to avoid permission issues
const oauthDb = new SQLiteOAuthDatabase({
  databasePath: '/var/lib/atxp/tokens.db'
})
If you’re experiencing connection timeouts:
  • Increase the connectionTimeout value
  • Check if the database file is locked by another process
  • Ensure sufficient disk space is available
const oauthDb = new SQLiteOAuthDatabase({
  databasePath: './tokens.db',
  connectionTimeout: 30000 // 30 seconds
})

@atxp/client

Client-side integration for MCP clients with OAuth authentication.

@atxp/express

Server-side middleware for MCP servers with payment processing.

@atxp/redis

Redis OAuth database for high-scale applications.

@atxp/common

Shared utilities and types used across ATXP packages.