@atxp/sqlite

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)

SQLiteOAuthDatabaseOptions

required

Configuration options for the SQLite database connection.

Show SQLiteOAuthDatabaseOptions properties

string

required

Path to the SQLite database file. If the file doesn’t exist, it will be created automatically.

boolean

default:"true"

Whether to automatically create the required database tables on initialization.

number

default:"5000"

Connection timeout in milliseconds.

Methods

Promise<void>

Saves an OAuth access token in the database.

Show saveAccessToken arguments

string

required

Unique identifier for the user associated with the access token.

string

required

The OAuth access token value to store.

AccessToken

required

URL associated with the access token.

Promise<AccessToken | null>

Retrieves an OAuth access token from the database.

Show getAccessToken arguments

string

required

Unique identifier for the user associated with the access token.

AccessToken

required

URL associated with the access token.

Promise<boolean>

Deletes an OAuth token from the database.

string

required

Unique identifier for the token to delete.

Promise<boolean>

Checks if a token exists in the database.

string

required

Unique identifier for the token to check.

Promise<string[]>

Lists all token keys stored in the database.

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
}

string

required

Path to the SQLite database file. Can be a relative or absolute path.

boolean

default:"true"

Whether to automatically create the required database tables on initialization.

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://search.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('search_search', {
  query: 'example query'
})

Integration with ATXP Server

Use SQLite storage with the ATXP server for persistent session management:

import { atxpExpress, ATXPAccount } 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({
  destination: new ATXPAccount(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

Database file permission errors

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'
})

Connection timeout errors

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.

Overview

Build Agents

Monetize MCP Tools

Developer Tools

API Reference

Overview

Installation

API Reference

Classes

`SQLiteOAuthDatabase`

Interfaces

`SQLiteOAuthDatabaseOptions`

Usage Examples

Integration with ATXP Client

Integration with ATXP Server

Configuration

Database File Location

Environment Variables

Database Schema

Troubleshooting

Common Issues

@atxp/client

@atxp/express

@atxp/redis

@atxp/common

​Overview

​Installation

​API Reference

​Classes

​SQLiteOAuthDatabase

​Interfaces

​SQLiteOAuthDatabaseOptions

​Usage Examples

​Integration with ATXP Client

​Integration with ATXP Server

​Configuration

​Database File Location

​Environment Variables

​Database Schema

​Troubleshooting

​Common Issues

​Related Packages

@atxp/client

@atxp/express

@atxp/redis

@atxp/common

Overview

Installation

API Reference

Classes

`SQLiteOAuthDatabase`

Interfaces

`SQLiteOAuthDatabaseOptions`

Usage Examples

Integration with ATXP Client

Integration with ATXP Server

Configuration

Database File Location

Environment Variables

Database Schema

Troubleshooting

Common Issues

Related Packages