# MCP reference

Use this reference when operating DexSQL through an MCP client. The `dexsql mcp`
command serves tools and English documentation over local stdio. User setup is
documented in the [CLI guide](../cli/index.md#connect-an-ai-client).

## Start a task

1. Call `resources/list` to discover the available manuals. Use `list_tables`
   and `describe_table` with `{"name":"methods"}` to check tables and columns
   without opening an input.
2. Call `open_dataset` with local paths, for example
   `{"inputs":["/absolute/path/app.apk"]}`. Relative paths use the server's working
   directory. Several paths form one dataset. Inspect returned diagnostics,
   `has_dex` and `archive_inputs`; archives without DEX can still provide resources.
3. Use the returned `dataset_id` in later calls. Start with a selective SQL query,
   then inspect matched methods or resources. Do not invent dataset or file IDs.
4. Follow the continuation fields described by each tool. Query pagination
   re-executes SQL, so use a deterministic `ORDER BY` with a unique tie-breaker.
5. Reuse the dataset for related work. Call `close_dataset` when it is no longer
   needed. A server restart invalidates all dataset IDs.

Example `query` arguments (replace the ID with the one returned by `open_dataset`):

```json
{
  "dataset_id": "dataset-1",
  "sql": ["SELECT descriptor FROM classes ORDER BY file_id, class_idx LIMIT 20"]
}
```

## Tool reference

| Tools | Reference |
| --- | --- |
| `open_dataset`, `list_datasets`, `close_dataset` | [Lifecycle, cancellation and limits](lifecycle.md) |
| `list_tables`, `describe_table` | [Table meanings](../sql/schema.md); tool output gives current names and types |
| `query` | [SQL requests, result encoding and pagination](query.md) |
| `decode` | [Method summaries, smali and navigation context](smali.md) |
| `get_manifest`, `get_manifest_components` | [APK tools](apk.md) |
| `list_resource_files`, `read_resource`, `query_resources` | [APK tools](apk.md) |

Use `tools/list` for exact argument schemas and defaults. [SQL examples](../sql/examples.md)
and [call references](../sql/calls.md) provide reusable query patterns.

## Documentation resources

`resources/list` returns the complete English document catalog, including pages
that have no links from other documents. Listing requires no prior resource reads
or open dataset. Use `resources/read` with a listed URI to retrieve one page.
All listed documents are included in the executable and match its
version; no separate document files or network connection are needed. Links in
resource responses use MCP URIs. A resource URI is `dexsql://` followed by the
Markdown file's path relative to the documentation root, including `.md`. Directory
index pages retain their filenames. There are no aliases or resources outside
this documentation tree.

## Session behavior

Opening an input prepares a dataset for successive queries. Reopening the same
path creates an independent dataset. If a source changes, close and reopen its
dataset before continuing. Closing rejects new work while already accepted work
may finish within its deadline.

Running timeout or cancellation closes the affected dataset; reopen it to
continue. Queued cancellation preserves existing datasets. Check `list_datasets`
after cancellation. See [lifecycle and limits](lifecycle.md) for quotas and retry
rules.

stdout contains MCP messages only; diagnostics use stderr. Persistent disk caches
are managed by the [CLI cache commands](../cli/cache.md).

---

Copyright (c) 2026 LSPosed Developers. Documentation licensed under [MIT](../license.md).