This server provides a stateful local Spark/PySpark MCP interface for exploring data and authoring Fabric notebooks, with tools to run code and SQL, inspect and manage the session, and work with Fabric lakehouses and tables.
Run PySpark/Python cells against a persistent session (state persists across calls; spark, sc, F, T, Window pre-imported).
Run Spark SQL and get results as a text table, with optional row limits and auto-mounting of referenced Fabric tables.
Inspect the live session: Spark version, master, current database, catalog databases, and registered Fabric lakehouses.
Reset the runtime to restart Spark and wipe all variables, imports, and mounted tables.
List Fabric lakehouses and their Delta tables.
Mount tables or entire lakehouses by name so they become queryable as <lakehouse>.<table>, including custom pre-registration for use in run_code.
Work like a Fabric notebook: table resolution by name, local sandboxing/write modes, notebook execution, notebookutils/mssparkutils, and a real /lakehouse/default/Files directory mirror for file access.
Provides a stateful local Spark session for exploring and authoring code against Delta tables, including mounting Fabric lakehouse tables, running SQL and PySpark, creating local Delta shallow clones, and performing operations such as saveAsTable, INSERT, MERGE, and DeltaTable.forName.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@local-spark-mcp Run a SQL query to get count of orders by status"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that gives an agent a stateful local Spark session to work in — a Jupyter-notebook-shaped surface with the UI stripped away. The agent runs PySpark "cells" against a long-lived session (state persists across calls), runs SQL and gets rows back, and manages the runtime through tools.
The purpose is local exploration in service of authoring PySpark notebooks that will run on Microsoft Fabric: figure things out locally against the same OneLake Delta data, then hand the honed code to the user as a notebook to run on Fabric with a reasonably similar outcome — no cloud compute burned while exploring.
Version 0.2.x: the core session plus notebook parity — a Fabric notebook
from the Git export runs unmodified against real OneLake data, in a sandbox by
default. Validated live on Linux/WSL and Windows. See CLAUDE.md for the
architecture and the locked design decisions.
Related MCP server: Fabric Data Engineering MCP Server
uvx, from GitHub)No clone or build needed — uvx installs and runs it in an ephemeral
environment. Register it as an MCP server in Claude Code (.mcp.json):
{
"mcpServers": {
"local-spark": {
"command": "uvx",
"args": ["--from", "git+https://github.com/methodify/local-spark-mcp", "local-spark-mcp"],
"env": { "LOCAL_SPARK_WORKSPACE_NAME": "Data Warehouse" }
}
}
}Runs on Linux/WSL and Windows (both validated end to end against live OneLake). Prerequisites on the host:
Java 17 for Spark 3.5 (the server prefers a vfox-managed JDK 17, else
JAVA_HOME; or set runtime.java_home / LOCAL_SPARK_JAVA_HOME). System
Java 21 will not work.
az login — OneLake/Fabric auth is ambient via DefaultAzureCredential.
Windows: nothing extra. Hadoop's winutils.exe/hadoop.dll (required for
Spark to start at all on Windows) ship inside the package; point
runtime.hadoop_home at your own Hadoop if you prefer. Python 3.11 is used on
every platform — it matches Fabric Runtime 1.3, and pyspark 3.5.0's Python
workers crash on Windows under 3.12.
The prebuilt OneLake token-provider jar ships inside the package, so Fabric mode
works out of the box (no sbt needed). First run downloads PySpark/Delta jars and
is slow; subsequent runs reuse the cached environment. Use --refresh to pick up
a new commit: uvx --refresh --from git+https://github.com/methodify/local-spark-mcp local-spark-mcp.
Spark Python workers run the same interpreter as the driver, so a library
installed into the server's environment is importable in both run_code and in
distributed code (mapPartitions / UDFs). Install such libs into that env — e.g.
uvx --with jageocoder --with postal --from git+…/local-spark-mcp local-spark-mcp
— and set any data-dir env vars (and/or PYTHONPATH) under [spark.env] in
local-spark.toml; those are applied to both the driver and the workers. (A
runtime sys.path.append only affects the driver — workers won't see it.)
Tables by name. Lakehouses are Spark databases; spark.table("dataverse.custtable"),
spark.sql, saveAsTable, INSERT, MERGE, and DeltaTable.forName resolve
<lakehouse>.<table> on first touch, with no mount step. Set
[lakehouses] default (env LOCAL_SPARK_DEFAULT_LAKEHOUSE) and unqualified
names resolve against it, as on Fabric.
Write policy ([runtime] write_mode, env LOCAL_SPARK_WRITE_MODE).
sandbox (default): nothing reaches OneLake — a table you write becomes a
local Delta shallow clone (metadata only, so reads stay live and the first
write is quick) and new tables land locally; later reads in the session see
them. readonly: sandbox plus refusal of table creation and DeltaTable.forName.
writethrough: writes go to OneLake. shadow_status lists the local shadows
with a state: read (materialized by a read, unchanged) or written (has
local writes); discard_shadow resets them, or only the read or written
ones with only=. Shadows are session-scoped unless persist_shadow = true.
run_notebook runs a notebook from its Git .py source cell by cell in
the persistent namespace, with cell selection ("0-4,7"), parameters
(applied after the PARAMETERS CELL), and the notebook's own default lakehouse.
%pip / !pip / %run lines are reported, not run — bring libraries in with
uvx --with. [notebooks] root (env LOCAL_SPARK_NOTEBOOKS_ROOT) lets you
address notebooks by Fabric display name.
notebookutils / mssparkutils are importable: credentials.getSecret
(Key Vault), variableLibrary.getLibrary (Fabric REST), fs.ls / fs.exists
/ fs.mount, notebook.run / runMultiple / exit, session.stop,
runtime.context. Other members raise NotImplementedError naming the member.
/lakehouse/default/Files is a real directory — a link to a local mirror
of the default lakehouse's Files/, so open, os.listdir, subprocesses,
and native libraries reading a data directory all work. List the subtrees to
pull under [files] sync (env LOCAL_SPARK_FILES_SYNC) — subtrees like
lib/ or single files like _dwlib_hydrate_options.txt; unchanged files are
skipped, so a 2 GB tree downloads once. Writes land in the mirror; sync_files
pulls more on demand and pushes only in writethrough. Tables/ is never
mirrored. The mirror lives under ~/.local-spark/lakehouses/<workspace-id>/<lakehouse-id>/Files
(env LOCAL_SPARK_MIRROR_ROOT), shared by every project that uses that
lakehouse, and LOCAL_SPARK_FILES_ROOT names it for code that avoids the
global path.
/lakehouse pathThe link is one global path per machine, so a lockfile records which session owns it and the server refuses to repoint it while another live session holds it for a different lakehouse (session_info reports this, and the mirror path still works).
Linux and WSL: /lakehouse must exist and be writable by you. One-time
setup: sudo mkdir /lakehouse && sudo chown $USER /lakehouse. If /lakehouse
is already a symlink into a directory you own, the server uses it as is. The
server never creates /lakehouse itself; it reports the command and runs
without the link.
Windows: C:\lakehouse\default is a directory junction, created without
elevation. A path beginning with / resolves against the current drive, so
/lakehouse/default/Files works when the session runs from C:.
Configuration lives in a local-spark.toml file in the working directory (see
local-spark.example.toml), discovered by walking up from where the server is
launched. Environment variables (LOCAL_SPARK_*) override individual settings —
convenient in the MCP env block above when you don't want a file. With no
workspace configured the server runs local-only (no Fabric). Auth is ambient via
az login, so nothing in the config is secret.
To control which file is read, set LOCAL_SPARK_CONFIG to a path, or to none
to read no file at all (environment only). The console script accepts the same
as --config PATH / --no-config. At startup the server logs to stderr which
file it read (or why none), every LOCAL_SPARK_* override that applied, and the
origin of java_home / token_jar_path / hadoop_home; a value that fails
validation is reported with its origin, and the jar is checked for the classes
this version needs before Spark starts.
Java discovery, when java_home is not set: a vfox-managed JDK 17/11, then
JAVA_HOME, then java on PATH. Every candidate is resolved through
symlinks and junctions, a path to bin/java is normalized to its home, and a
JDK whose release file says anything other than 8, 11, or 17 is skipped. The
error lists each candidate and why it was rejected.
Apache License 2.0. See LICENSE, and NOTICE for the bundled third-party
components (Apache Hadoop winutils).
List the Fabric lakehouses available in this session. Each is registered as a Spark database; its tables are mounted on demand.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that lakehouses are registered as Spark databases and tables are mounted on demand, implying listing does not mount tables. However, it does not state read-only behavior, permissions, or effect of no lakehouses, so moderate transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the action, no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the zero-parameter interface and presence of an output schema, the description sufficiently explains purpose and key behavioral context. It covers what is listed and the on-demand mounting relationship, making it complete for a simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, so baseline is 4. The description adds no parameter-specific detail but explains the domain concept (lakehouses as databases), which is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists Fabric lakehouses available in the session, using the specific verb 'List' and resource 'Fabric lakehouses'. The additional detail about Spark database registration distinguishes it from list_tables and other sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool over alternatives, but implies usage for viewing session-available lakehouses. It mentions they are registered as Spark databases and tables mounted on demand, providing context but no explicit exclusions or alternative tool recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the Delta tables in a Fabric lakehouse. Tables are not queryable via SQL until you mount them with mount_table or mount_lakehouse.
| Name | Required | Description | Default |
|---|---|---|---|
| lakehouse | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses a key behavior ('Tables are not queryable via SQL until you mount them'), which is useful. However, it does not explicitly state that listing itself is read-only, or mention behavior on missing lakehouses or return format details. Score 3 reflects adequate but not rich transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose. The second sentence adds essential context about SQL queryability and mounting without any redundancy. It is precise and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with an output schema, the description covers the basic purpose and a workflow note, but it lacks parameter semantics and any mention of prerequisites or error cases. It is minimally viable but not fully complete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds only the vague phrase 'in a Fabric lakehouse.' It does not specify whether the 'lakehouse' parameter expects a name, ID, or path, nor any format constraints. The agent is left guessing about how to fill in the required parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and identifies the exact resource ('Delta tables in a Fabric lakehouse'). It also distinguishes the tool from siblings by focusing on tables rather than lakehouses and by mentioning the mounting workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: tables are not queryable via SQL until mounted, which tells the agent when this tool is useful (for discovery before mounting). It does not explicitly name alternatives for listing lakehouses, but the mount tools are mentioned, giving workflow guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mount ALL tables in a lakehouse as <lakehouse>.<table>. Convenient, but can register many tables at once.
| Name | Required | Description | Default |
|---|---|---|---|
| lakehouse | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that this mounts all tables and can register many at once, which is a key behavioral trait and potential risk. It does not mention reversibility or permissions, but the main caveat is covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the core action, no redundant information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and a single simple parameter, the description sufficiently covers purpose, scope, and a side effect. It doesn't address edge cases like existing mounts, but for a bulk mount tool this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptions (0% coverage), but the description uses the `<lakehouse>` placeholder to explain the parameter's role in the naming convention. This adds meaningful context to an otherwise bare parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Mount') and resource ('ALL tables in a lakehouse'), and clearly defines the naming convention (`<lakehouse>`.`<table>`). This distinguishes it from sibling tools like mount_table, which mounts a single table.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (when you want all tables) and warns about the side effect of registering many tables at once. It does not explicitly name alternatives like mount_table, but the contrast is clear from the phrase 'Mount ALL tables'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explicitly register one Fabric Delta table as <lakehouse>.<table>. Usually unnecessary — run_sql auto-mounts referenced tables — but useful to pre-register a table for use in run_code.
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | ||
| lakehouse | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It explains the registration action and the naming pattern, but does not disclose idempotency, persistence, error conditions, or side effects. This is minimal but sufficient for a conceptually simple registration operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action and immediately followed by practical guidance. Every word contributes; no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers the tool's purpose, typical use case, and relationship to sibling tools. Given the low complexity (2 required string params, no nested objects) and existing output schema, nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and there are only 2 string parameters. The description adds meaning by showing the pattern `<lakehouse>`.`<table>`, directly mapping to the parameter names and clarifying that 'table' is a Fabric Delta table and 'lakehouse' is the lakehouse context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'register' with a clear resource 'one Fabric Delta table' as `<lakehouse>`.`<table>`. It distinguishes itself from run_sql and mount_lakehouse by explaining it pre-registers a table for run_code, contrasting with run_sql's auto-mounting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use ('useful to pre-register a table for use in run_code') and when not needed ('Usually unnecessary — run_sql auto-mounts referenced tables'). The alternative tool is named and contrasted clearly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reset the runtime: restart the Spark session and wipe all state — variables, imports, and mounted tables. Use to start from a clean slate.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses the destructive behavior ('wipe all state'), specifies what is affected ('variables, imports, and mounted tables'), and mentions restarting the session. It could have added more about irreversibility or impact on running work, but the core behavioral transparency is strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states the action and its effects, the second gives the usage. It is front-loaded with the key verb 'Reset', avoids fluff, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (no parameters) and the presence of an output schema, the description adequately covers the operation's purpose, effects, and use case. It is complete enough for an agent to select and invoke the tool correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is trivially 100%. The description does not need to explain parameters since there are none. Baseline for 0-parameter tools is 4, and no additional parameter semantics are necessary.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action ('Reset the runtime'), the specific resource ('Spark session'), and the scope ('wipe all state — variables, imports, and mounted tables'). This clearly differentiates it from sibling tools like run_code, run_sql, or mount_table.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear guidance on when to use ('Use to start from a clean slate'), which implies a scenario where the user needs to clear all state. It does not explicitly name alternatives or exclusions, but the usage context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a cell of Python/PySpark against the persistent session. State persists across calls; spark, sc, F, T, Window are pre-imported. Returns captured stdout and the last-expression echo, or the traceback if the cell raised.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and discloses key traits: persistent session, state preservation, pre-imported symbols, and return behavior (stdout, last-expression echo, or traceback). This is substantial coverage for a code execution tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary purpose. Every element earns its place: what it runs, persistence, pre-imports, and return behavior. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (1 required param) and the description covers purpose, statefulness, available symbols, and return values. The presence of an output schema further clarifies the return structure, making this description adequate on its own.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single 'code' parameter is explained as a cell of Python/PySpark, and the pre-imports listed clarify what is available in scope. This adds meaning beyond the raw schema ('code' string) and compensates for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Run') and resource ('a cell of Python/PySpark against the persistent session'), clearly distinguishing it from sibling tools like run_sql. It states exactly what the tool does without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it is for Python/PySpark cells, state persists across calls, and pre-imports are listed. It implicitly distinguishes from SQL execution (run_sql) but does not explicitly state when not to use or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a Spark SQL statement and return rows as a text table. Reference Fabric tables by name (lakehouse.table) — they auto-mount on first use and stay available for the session. limit caps returned rows (default from config, ~100) and the result flags truncation.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It reveals the text-table return format, truncation flag, auto-mounting, and session availability. It does not explicitly state whether statements are read-only, but the implied use case focuses on querying.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, front-loaded with the primary action. Every sentence provides essential information without redundancy, making it efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers usage, parameter semantics, and key behaviors like auto-mounting and truncation. Since an output schema exists, return values need not be detailed. The main gap is the lack of explicit read-only or write clarification, which is minor for this query-oriented tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptions for parameters, but the description compensates fully: 'sql' is explained as the Spark SQL statement, and 'limit' is described as capping returned rows with a default from config (~100). This adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs a Spark SQL statement and returns rows as a text table, using a specific verb and resource. It distinguishes from sibling tools like run_code by emphasizing SQL execution and the text-table output.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool, such as referencing Fabric tables and auto-mounting behavior. However, it does not explicitly mention when not to use it or name alternative tools, like run_code.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show the live Spark session: version, master, current database, the catalog databases, and any Fabric lakehouses registered this session.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. The verb 'Show' strongly implies a non-destructive, read-only operation, and the term 'live' adds context that it reflects the current state. However, it does not explicitly state that it has no side effects or what happens if no session exists, so it is not a perfect 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the core action ('Show the live Spark session') and then lists the details. Every word adds value, and there is no redundancy or irrelevant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple zero-parameter tool with an output schema. The description fully conveys what information is available, and the output schema provides the return structure. No additional context is needed for the agent to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is no schema detail to explain. The description still adds value by enumerating the specific information returned (version, master, current database, catalog databases, lakehouses), which gives the agent a clear picture of the tool's output even without parameter definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Show') and clearly identifies the resource (live Spark session) and its key contents (version, master, current database, catalog databases, lakehouses). This makes the tool's purpose unambiguous and distinguishes it from siblings like run_code and run_sql, which execute code rather than introspect the session.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for inspecting current session state, which provides clear context for when to use it. It does not explicitly mention alternatives or when not to use it, but the purpose is obvious enough that an agent can select it appropriately among the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0list_lakehouseslist_tablesmount_lakehousemount_tablereset_runtimerun_coderun_sqlsession_infoEach tool has a clearly distinct role: running Python vs SQL, inspecting session state, resetting, and managing lakehouse/table mounting. The potential overlap between mount_table and mount_lakehouse is clearly scoped.
Most tools follow a verb_noun snake_case pattern (run_code, run_sql, list_lakehouses, mount_table), but session_info is a noun_noun exception. Still consistent style overall.
8 tools is well-scoped for a Spark session server, covering execution, SQL, state management, and catalog operations without redundancy.
The surface covers the full workflow: execute code, query SQL, inspect session, reset state, list and mount data sources. Auto-mounting in run_sql and explicit mounting in mount_* cover the data access lifecycle.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Your Databricks Lakehouse in natural language: run SQL on your SQL warehouses, track long-running qu
The all-in-one data stack for agents. Upload files, run SQL, evolve tables, and render charts.
Individual-analyst context layer: recall, remember, and reconcile your data and engineering context.
The grounded data layer for any LLM: governed SQL, metrics, lineage and catalog over your data.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/methodify/local-spark-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
