@taxida-community/tesseract

v1.3.2

Published

a day ago

Official Taxida MCP server and developer toolkit for cab search, booking, and trip workflows.

Tesseract

Tesseract is the official @taxida-community/tesseract npm package and Model Context Protocol (MCP) server for cab search, booking, and trip workflows. It is Taxida's AI platform — the single integration point for any MCP-compatible agent or agentic SDK.

Compatibility: Tesseract works with any agent or agentic SDK that supports the Model Context Protocol — including Claude Code, Claude Desktop, OpenAI Agents SDK, LangChain, CrewAI, and others. The setup steps in this document are written specifically for Claude Code (CLI) and Claude Desktop. For other MCP-compatible clients, refer to their documentation for how to register a stdio or remote MCP server.

Tesseract supports two transports:

| Transport | How it runs | When to use | |-----------|-------------|-------------| | stdio | npx spawns a local process on your machine | No Node.js already installed, or prefer zero config — use the auto-installer | | HTTP (Streamable) | Hosted server at https://tesseract.taxida.in/mcp | No local Node.js, server-side agents, CI/CD pipelines, or just prefer a URL over npx |

Both transports work with Claude Code, Claude Desktop, and any MCP-compatible client.

Available Tools

| Tool | Transport | Description | |------|-----------|-------------| | resolve_location | Both | Resolve a free-text address or landmark to GPS coordinates | | get_trip_price_estimate | Both | Get approximate fare before exact locations are confirmed | | cab_search | Both | Search available cabs (ONE_WAY, ROUND_TRIP, LOCAL rental, AIRPORT_TRANSFER) | | cab_block | Both | Hold a cab from search results temporarily (5–10 min TTL) | | block_release | Both | Release a held cab block without booking | | booking_confirm | Both | Confirm a cab booking (requires auth) | | booking_cancel | Both | Cancel a confirmed booking (requires auth) | | list_user_bookings | Both | List the authenticated user's recent bookings | | plan_trip_itinerary | Both | Build a multi-leg trip plan; detects missing paired airport transfers | | check_itinerary_inventory | Both | Fetch live vehicle availability and fares for all itinerary legs | | confirm_itinerary_booking | Both | Book all legs of a planned itinerary (requires inv_check_id) | | list_supported_cities | Both | List all Indian cities supported for cab booking | | list_supported_airports | Both | List all supported Indian airports (with IATA codes) | | get_otp | stdio only | Send OTP to a phone number to begin authentication | | verify_otp | stdio only | Verify OTP and activate the booking session |

HTTP (remote) transport: get_otp and verify_otp are not available — 13 tools total. Authentication is handled automatically via OAuth 2.1 — the OTP you enter in the browser during the OAuth flow is used to obtain your Taxida session token, which is embedded in the OAuth access token and used silently for all booking operations.
stdio (local) transport: All 15 tools are available. Call get_otp then verify_otp before booking_confirm, booking_cancel, or confirm_itinerary_booking.

Full tool contracts are documented in docs/API_REFERENCE.md.

Install Claude

Install Claude Code (CLI)

Claude Code is Anthropic's official CLI for working with Claude AI. Install it with npm:

npm install -g @anthropic-ai/claude-code

Verify the install:

claude --version

Windows: If claude is not found after install, open a new terminal. If it still fails, use claude.cmd or ensure the npm global bin directory is in your PATH (npm config get prefix → add <prefix>\bin to PATH).

You will be prompted to log in with your Anthropic account on first run. A Claude subscription or API key is required.

Install Claude Desktop

Claude Desktop is Anthropic's graphical AI assistant app. Download and install it for your OS:

| OS | Download | |----|----------| | macOS | claude.ai/download — download the .dmg, open it, drag Claude to Applications | | Windows | claude.ai/download — download the .exe installer and run it | | Linux | Not officially supported. Use Claude Code (CLI) instead. |

After install, launch Claude Desktop and sign in with your Anthropic account. A Claude subscription or API key is required.

Setup — stdio (local)

The stdio transport runs Tesseract as a local process on your machine. Claude communicates with it via stdin/stdout. Node.js is required.

Quick Install (stdio)

Run one command to install Node.js (if needed), set up Tesseract, and configure Claude Desktop automatically.

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/taxida-mcp/taxida-mcp/main/scripts/install.sh | bash

Windows PowerShell:

irm https://raw.githubusercontent.com/taxida-mcp/taxida-mcp/main/scripts/install.ps1 | iex

This script will:

Detect your OS and install Node.js 20+ if missing
Verify @taxida-community/tesseract through npx
Automatically update Claude Desktop MCP config on macOS and Windows
Preserve existing MCP servers and backup the config before editing

For Claude Code (CLI) or manual setup, continue with the steps below.

Prerequisites — Install Node.js

Node.js LTS (latest) is required. Follow the steps for your operating system.

macOS

Option 1 — Homebrew (recommended)

brew install node

If npx is not found after install, add Node.js to your PATH. Add this line to ~/.zshrc (or ~/.bash_profile if using bash):

export PATH="/opt/homebrew/bin:$PATH"

Then reload your shell:

source ~/.zshrc

Option 2 — nvm (Node Version Manager)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.zshrc
nvm install --lts
nvm use --lts

Option 3 — Official installer

Open https://nodejs.org and download the LTS version for macOS.
Open the downloaded .pkg file and follow the installer prompts.

Verify after any option:

node --version
npx --version

Windows

Option 1 — winget (recommended, built into Windows 10/11)

winget install OpenJS.NodeJS.LTS

Open a new terminal after install and verify:

node --version
npx --version

Note: On Windows, npx may not be recognised even after a successful install. Use npx.cmd instead — it is installed alongside Node.js in the same directory and works identically:
npx.cmd --version
Use npx.cmd anywhere this guide says npx.

Option 2 — Chocolatey

choco install nodejs-lts

Option 3 — nvm-windows

winget install CoreyButler.NVMforWindows

Then open a new terminal:

nvm install lts
nvm use lts

Option 4 — Official installer

Open https://nodejs.org and download the LTS Windows installer (.msi).
Run the installer. Make sure "Add to PATH" is checked.

If npx is not found after any install, add Node.js to PATH manually:

Open Start → Search → "Environment Variables" → click Edit the system environment variables.
Click Environment Variables.
Under System variables, select Path and click Edit.
Click New and add the Node.js install directory (typically C:\Program Files\nodejs\).
Click OK on all dialogs, then open a new terminal and verify again.

Linux

Ubuntu / Debian — NodeSource (recommended)

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

Fedora / RHEL / CentOS — NodeSource

curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
sudo dnf install -y nodejs

Arch Linux

sudo pacman -S nodejs npm

Any distro — nvm

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install --lts
nvm use --lts

Verify after any option:

node --version
npx --version

If npx is not in PATH after install:

# Find where npm global binaries are installed
npm config get prefix

# Add to ~/.bashrc or ~/.zshrc
export PATH="$(npm config get prefix)/bin:$PATH"

# Reload your shell
source ~/.bashrc

Install Tesseract

No global install is needed. npx fetches and runs the latest version automatically:

npx -y @taxida-community/tesseract

Windows: use npx.cmd instead of npx.

Alternatively, use the one-command automatic installer which also configures Claude Desktop for you:

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/taxida-mcp/taxida-mcp/main/scripts/install.sh | bash

Windows PowerShell:

irm https://raw.githubusercontent.com/taxida-mcp/taxida-mcp/main/scripts/install.ps1 | iex

The installer will:

Detect your OS
Install Node.js 20+ if missing or outdated
Verify @taxida-community/tesseract through npx
Automatically update Claude Desktop MCP config on macOS and Windows
Preserve existing Claude MCP servers and backup the config before editing
Print a restart instruction

For Linux, Claude Desktop config paths are not always standard. If the installer cannot detect a supported config path, it prints the manual config as a fallback.

Configure Claude Code (stdio)

Claude Code reads MCP server configuration from ~/.claude.json.

Step 1 — Register the server:

claude mcp add taxida --scope user -- npx -y @taxida-community/tesseract

Windows users: use npx.cmd instead:

claude mcp add taxida --scope user -- npx.cmd -y @taxida-community/tesseract

Step 2 — Verify:

claude mcp list

taxida should appear with status connected.

Step 3 — Use it:

Start a Claude Code session and try a natural language request:

Search for cabs from Connaught Place, Delhi to Indira Gandhi International Airport for tomorrow at 6 AM

Claude will invoke the cab_search tool automatically.

Manual configuration (edit ~/.claude.json directly):

{
  "mcpServers": {
    "taxida": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@taxida-community/tesseract"]
    }
  }
}

Windows: replace "npx" with "npx.cmd".

Version pinning: The -y flag always fetches the latest published version. To pin to a specific version:
"args": ["-y", "@taxida-community/[email protected]"]

Configure Claude Desktop (stdio)

Claude Desktop reads MCP configuration from a JSON file. The file location depends on your OS:

| OS | Config file path | |----|-----------------| | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\Claude\claude_desktop_config.json | | Linux | ~/.config/Claude/claude_desktop_config.json |

Step 1 — Open the config file:

macOS:

open ~/Library/Application\ Support/Claude/

Windows (PowerShell):

notepad "$env:APPDATA\Claude\claude_desktop_config.json"

Linux:

nano ~/.config/Claude/claude_desktop_config.json

Step 2 — Add Tesseract:

If the file does not exist yet, create it. Add or merge the following:

{
  "mcpServers": {
    "taxida": {
      "command": "npx",
      "args": ["-y", "@taxida-community/tesseract"]
    }
  }
}

Windows: replace "npx" with "npx.cmd".

Version pinning: To pin to a specific version:
"args": ["-y", "@taxida-community/[email protected]"]

If the file already has other MCP servers, add only the "taxida" block inside the existing "mcpServers" object.

Step 3 — Restart Claude Desktop:

Fully quit Claude Desktop (use Quit from the menu or system tray — do not just close the window) and relaunch it.

Step 4 — Confirm the server is connected:

Click the Settings icon (⚙) in the top-right corner.
Select Developer from the left sidebar.
Under Model Context Protocol, taxida should appear with a green indicator.

If it shows red, check that Node.js is installed and npx is in your PATH, then restart Claude Desktop again.

Step 5 — Use Tesseract tools:

Open a new conversation.
Click the tools icon (🔨) in the bottom-left of the message input box.
You should see all 14 tools: resolve_location, get_trip_price_estimate, cab_search, cab_block, block_release, booking_confirm, booking_cancel, list_user_bookings, plan_trip_itinerary, confirm_itinerary_booking, list_supported_cities, list_supported_airports, get_otp, verify_otp. Toggle them on.
Try a natural language request:

Search for cabs from MG Road, Bangalore to Kempegowda International Airport for tomorrow at 8 AM

Authentication

Tesseract uses OTP-based authentication for stdio sessions. On first use, Claude will:

Call get_otp with your phone number — an OTP is sent via SMS.
Ask you to enter the OTP.
Call verify_otp to activate your session.

The session token is held in memory for the duration of the conversation. No tokens or credentials are stored on disk.

Note: For the HTTP (remote) transport, authentication is handled via OAuth 2.1 — see the Setup — HTTP (remote) section. You will not need to call get_otp or verify_otp in remote sessions.

Setup — HTTP (remote)

Tesseract runs as a hosted HTTP MCP server using the MCP Streamable HTTP transport. No local Node.js installation is needed.

When to use remote MCP

| Use case | Notes | |----------|-------| | Claude Code or Claude Desktop | Works with both transports — use HTTP if you prefer not to install Node.js locally | | No local Node.js available | HTTP is the easier choice | | Server-side agent or CI/CD pipeline | HTTP only | | Custom SDK integration | HTTP only |

Endpoint

| Path | Method | Purpose | |------|--------|---------| | https://tesseract.taxida.in/health | GET | Health check — returns {"status":"ok","sessions":<n>} | | https://tesseract.taxida.in/mcp | POST | Send MCP JSON-RPC requests (initialize, tools/list, tools/call) | | https://tesseract.taxida.in/mcp | GET | Open SSE stream for server-to-client notifications | | https://tesseract.taxida.in/mcp | DELETE | Terminate a session explicitly |

The /mcp endpoint requires a valid OAuth 2.1 Bearer token (Authorization: Bearer <access_token>). MCP clients that support OAuth 2.1 (such as Claude Code 2.1.70+) handle the full authentication flow automatically — including dynamic client registration, PKCE, and token refresh.

Configure Claude Code (remote)

claude mcp add taxida-remote --transport http \
  --url https://tesseract.taxida.in/mcp \
  --scope user

Or add it manually to ~/.claude.json:

{
  "mcpServers": {
    "taxida-remote": {
      "type": "http",
      "url": "https://tesseract.taxida.in/mcp"
    }
  }
}

Verify:

claude mcp list

taxida-remote should appear as connected.

Configure Claude Desktop (remote)

Claude Desktop connects to remote MCP servers via the custom connector option in the UI — not via the config file.

Step 1 — Open Connectors settings:

Launch Claude Desktop.
Click your profile icon or open Settings.
Navigate to Settings → Connectors.
Click Add custom connector.

Step 2 — Enter the Tesseract endpoint:

| Field | Value | |-------|-------| | Name | Tesseract (or any name you prefer) | | URL | https://tesseract.taxida.in/mcp |

Click Save (or Add).

Step 3 — Confirm the connector is active:

The Taxida connector should appear in your connectors list with a green connected indicator. If it shows an error, verify your internet connection and try again.

Step 4 — Use Tesseract tools:

Open a new conversation. All 12 tools will be available automatically: resolve_location, get_trip_price_estimate, cab_search, cab_block, block_release, booking_confirm, booking_cancel, list_user_bookings, plan_trip_itinerary, confirm_itinerary_booking, list_supported_cities, list_supported_airports. (get_otp and verify_otp are not available in remote sessions — authentication is handled automatically via OAuth 2.1.)

Session lifecycle

The HTTP transport is session-based. Each client connection gets a unique Mcp-Session-Id assigned by the server on the first initialize request.

How sessions work:

Initialize — Send POST /mcp with no Mcp-Session-Id header and an initialize JSON-RPC request. The server creates a session and returns Mcp-Session-Id in the response headers.
Subsequent requests — Include Mcp-Session-Id on every POST /mcp and GET /mcp request. The server routes it to the correct session.
Session expiry — Sessions expire after 30 minutes of inactivity. Requests with an expired session ID return 404 Not Found. Re-initialize to get a new session.
Explicit termination — Send DELETE /mcp with Mcp-Session-Id to close the session immediately. The server responds 200 OK and releases all resources.

Important nuances:

Session IDs are cryptographically random UUIDs — do not guess or construct them.
Sessions are independent — each verify_otp call stores the Taxida Bearer token in that session's context only. Two concurrent sessions for the same user do not share tokens.
Session loss on server restart — sessions are in-memory only. If the server restarts, all sessions are lost. Re-initialize and re-authenticate via get_otp / verify_otp. No credentials are stored on disk.
Session cap — the server enforces a maximum of 100 concurrent sessions by default. New initialize requests return 503 Service Unavailable when the cap is reached. Existing sessions are unaffected.

SSE and long-lived connections

The GET /mcp endpoint opens a Server-Sent Events (SSE) stream for server-to-client notifications.

Nuances for SSE:

Keep the connection alive — SSE streams are long-lived HTTP connections. Do not set aggressive timeouts on your HTTP client.
ALB / reverse proxy idle timeout — ensure the idle connection timeout is set to at least 3600 seconds. The default AWS ALB timeout of 60 seconds will kill active SSE streams. The hosted UAT endpoint already has this configured.
Sticky sessions — if you run multiple Tesseract instances behind a load balancer, enable session stickiness (e.g. ALB cookie-based stickiness). The Mcp-Session-Id is bound to a specific server instance; routing the same session to a different instance returns 404.
Reconnection — if the SSE stream drops, re-initialize the MCP session from scratch. Do not attempt to resume a dropped stream with the old session ID.

Security

Runtime logs are written to stderr so stdout remains safe for MCP JSON-RPC.
Redaction covers authorization headers, bearer tokens, OTP-like fields, phone-like values, and email addresses.
Never commit .env, tokens, OTPs, private URLs, customer data, logs, or screenshots with sensitive data.
Report vulnerabilities privately using SECURITY.md.

Privacy Policy

Last updated: 2026-05-25

Data Collected

Tesseract collects the following data:

| Data | Purpose | Retention | |------|---------|-----------| | Phone number | Customer authentication; primary user identifier | Stored in MySQL (oauth_refresh_tokens table) as long as a refresh token exists | | OTP code | Verifying customer identity | Transmitted to Taxida API in real-time; never stored | | Taxida session token | Authorizing trip-service API calls | AES-256-GCM encrypted and stored in MySQL alongside the refresh token | | Refresh token | Maintaining long-lived sessions (30-day TTL) | Stored in MySQL; deleted on revocation or new login | | Access token (JWT) | Short-lived session credential (1-hour TTL) | Stateless; never stored server-side | | Pickup/drop locations | Fare estimation and booking | Transmitted to Taxida API; not stored by MCP server | | Trip itinerary details (leg dates/times, places to visit, route notes) | Multi-leg trip planning and driver dispatch via Taxida backend | Transmitted to Taxida API; not stored by MCP server | | Booking details | Confirming/cancelling trips | Transmitted to Taxida API; not stored by MCP server |

Data Storage

Tesseract uses a MySQL database for OAuth token persistence:

Refresh tokens are stored in the oauth_refresh_tokens table, keyed by phone number. They persist until explicitly revoked (via POST /oauth/revoke) or replaced by a new login.
Taxida session tokens are stored alongside refresh tokens, AES-256-GCM encrypted. They are used to authorize downstream booking API calls without requiring re-authentication.
Access tokens (JWTs) are stateless and short-lived (1 hour). They are never stored server-side — only the signature verification key is held.
OTP codes are never stored. They are transmitted directly to the Taxida API for real-time verification and discarded immediately.
In-memory session state (active MCP sessions) is cleared when the session expires (30 minutes of inactivity), the client sends a DELETE request, or the server process restarts.
Trip itinerary details (leg dates/times, pickup/drop coordinates, places to visit, route notes) are held in memory only for the duration of the planning conversation (1-hour TTL) and are never written to disk or database by the MCP server. They are forwarded to the Taxida trip-service API for booking and driver dispatch.

Third-Party Connections

All trip-related operations are forwarded to the Taxida trip-service API. By using this connector, you agree to Taxida's Terms of Service and Privacy Policy.

Data Sharing

No user data is shared with third parties beyond the Taxida trip-service API required to fulfill the requested operations.

Contact

For privacy inquiries, contact: [email protected]

For support, contact: [email protected]

License

MIT. See LICENSE.