Build on Console
Use Console as the workbench for an assistant or workflow of your own. Choose the languages and arguments the model sees, describe the available data, and prepare its packages, connections, and helper functions. Your application manages the model and conversation; Console manages the sessions, package preparation, sandbox, and recordings.
Choose an integration
| Your application | Start here |
|---|---|
| An ellmer chat in R | Use Console from R, including session configuration and a complete analysis example. |
| Python code or a model framework | Use Console from Python, with synchronous and asynchronous clients and framework adapters. |
| Your own MCP client | Drive send directly: submit cells, collect output, answer input, interrupt work, and restart. |
| An existing coding agent | Install and connect, then use the same configuration files to customize its Console session. |
Use the supplied adapters when integrating with a model framework so the model receives the connected server’s actual tool schema. For exact fields and signatures, see Tool settings, the send tool, the R API, and the Python API.
Build a data assistant
Give an assistant SQL access to a sales database, describe its tables, and connect the configured tool to a client. This walkthrough uses an existing SQLite database at data/sales.sqlite, with an orders table containing order_date, region, and revenue columns. The same configuration works with an MCP client or the R and Python packages.
The main example uses a read-only SQL connection. The session setup section also shows alternatives for preparing R objects or initializing from application code. For exact settings, see Tool configuration.
Choose languages and arguments
Create a configuration file for your project, then select the interface you want to expose. For example, a SQL-only interface can omit package requests and interactive input:
languages: [sql]
tool:
parameters:
requirements:
enabled: false
stdin:
enabled: falseThe tool accepts SQL, polling, and the remaining control arguments. R and Python source fields, requirements, and stdin are absent from the advertised schema and rejected if supplied, including as null. Use [r], [python], or a combination of languages for other tasks.
Language selection controls the interface; SQL can still use an R or Python connection underneath. Use sandbox permissions and database permissions to control what the workload can access. Tool configuration lists the available settings, including controls for nested arguments.
Prepare the session
Select interpreters and startup packages and preparation policies in configuration. You can choose when packages may be prepared, from a fixed startup set to adding packages during a session. Preparing a package makes it available; loading data and defining variables require code in the session. Choose the setup approach that fits your session.
Select a database connection
For the SQL interface above, add a startup mapping to select a connection before the first SQL call. For example, with an existing SQLite database at data/sales.sqlite:
startup:
language: python
code: |
import sqlite3
connection = sqlite3.connect("file:data/sales.sqlite?mode=ro", uri=True)
_console.sql_connection(connection)This opens that database in read-only mode. The path is relative to Console’s launch directory, and Python must be available even when only SQL is exposed to the model.
startup is specifically for creating and selecting a SQL connection. It runs again after a worker restart, and the code must finish with a usable, user-created connection selected. See SQL connection startup for R and Python connection requirements.
Load R data and helpers
Console uses R’s native startup files by default. In a project’s .Rprofile, you can prepare objects before the agent’s first R call. For example:
sales <- data.frame(
region = c("North", "South"),
revenue = c(12000, 9000)
)
lockBinding("sales", globalenv())Replace the small example data frame with code that reads your project’s data, and define any helper functions in the same profile. lockBinding() prevents ordinary reassignment to sales; R code can unlock the binding, so this is not a security boundary.
Start Console in that project directory with R exposed. The profile runs again when R restarts; r.vanilla: true disables native startup files.
Initialize from your application
An application can also send setup code before giving the model access to the session. With the Python client, for example:
from mcp_console import MCPConsole
with MCPConsole(args=["serve", "-c", "languages=[python]"]) as console:
result = console.send(python="sales = {'North': 12000, 'South': 9000}")
print(result)
# Use this connection for the model's subsequent calls.Complete setup and handle any errors before handing the connection to the model. If the response says work is still running, poll without resubmitting the code. Keep the connection open for the conversation and repeat your setup after a restart or reconnect. Setup calls use the same enabled arguments and sandbox permissions as later calls.
Describe the data and workflow
Give the model information about the workspace it will receive: available tables or objects, column meanings, helper functions, and conventions for reporting results.
| Setting | Use |
|---|---|
tool.instructions |
Introduce the workspace in the server’s initialization instructions. |
tool.description |
Explain when and how to use the send tool. |
tool.parameters.<name>.description |
Describe a particular argument, such as sql or r. |
Each string replaces the corresponding generated text completely. To add context while keeping Console’s existing guidance, first export the resolved configuration:
mcp-console config resolve --full > application.yamlEdit the appropriate description in application.yaml to include your context. For a sales database, you might add:
The
orderstable contains one row per order, withorder_date,region, andrevenuecolumns. Revenue is recorded in USD. Use these columns to answer sales questions and state the date range used in each result.
Launch Console with the edited file:
mcp-console serve --config-file application.yamlChoose the languages and enabled arguments before exporting so the generated text and parameter entries match the interface. The client decides when to show initialization instructions and tool descriptions to the model. See Edit exported tool settings for the effect of omitted, null, and empty descriptions and for read-only schema metadata.
Name and connect your tool
For an existing MCP client, give the server registration a name that describes its purpose. For a client that launches Console in your project, run this from that directory to use the edited configuration:
mcp-console configure-client claude --directory . --name sales-data -- --config-file application.yamlThis names the server entry sales-data. The MCP tool remains send; configuration does not have a tool.name setting. See Client registration for client and launch options.
An application can expose its own function name while forwarding calls to Console. For example, install mcp-console[chatlas] and, with an existing chatlas chat, create a query_sales tool from the SQL server’s actual schema:
from chatlas import Tool
from mcp_console import MCPConsole
from mcp_console.chatlas import tools
with MCPConsole(args=["serve", "--config-file", "application.yaml"]) as console:
definition = console.get_tool("send")
send_tool = next(tool for tool in tools(console) if tool.name == "send")
query_sales = Tool(
func=send_tool.func,
name="query_sales",
description=definition.description or "",
parameters=definition.input_schema,
strict=False,
)
chat.set_tools([query_sales])
chat.chat("Which region has the highest total revenue?")set_tools() replaces the chat’s tool list. Using console.get_tool("send").input_schema preserves configured languages and hidden arguments; inferring a schema from the Python method’s signature would lose those settings. Reusing the framework adapter’s callback preserves its text and image result handling.
Interface stability
Console is a development preview; public interfaces can change. Build against the documented configuration, MCP tool, and client packages. The internal integrator control channel, hidden commands, and recording journal formats have no compatibility guarantees. See the interface boundaries for details.