# MCP Tools — Out of the Box

OBTO ships with a set of built-in MCP tools that cover the full application lifecycle — from creating an app to deploying code to generating live previews. These tools are available immediately after you connect your MCP endpoint.

***

### Tool Reference

#### Application Management

| Tool                    | Description                                                                                        | Type      |
| ----------------------- | -------------------------------------------------------------------------------------------------- | --------- |
| `obto_create_app`       | Create a new OBTO application with initial structure                                               | Mutating  |
| `obto_list_all_apps`    | List all applications in your environment                                                          | Read-only |
| `obto_find_app_by_name` | Look up a specific application by name                                                             | Read-only |
| `obto_read_app_map`     | Read the application map — a graph-like view of the app's structure                                | Read-only |
| `obto_fetch_app_graph`  | Fetch the application's knowledge graph (mind map) for understanding architecture and dependencies | Read-only |

#### Code Deployment

| Tool                  | Description                                                                                                                             | Type     |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `obto_upsert_record`  | **The primary deployment tool.** Create or update any artifact — pages, JavaScript modules, stylesheets, server scripts, client scripts | Mutating |
| `obto_create_route`   | Create a new Express.js route/API endpoint                                                                                              | Mutating |
| `obto_update_route`   | Update an existing route's code, path, method, or metadata                                                                              | Mutating |
| `obto_patch_artifact` | Surgically modify existing code using search & replace — for small, targeted changes                                                    | Mutating |

#### Code Reading

| Tool                       | Description                                               | Type      |
| -------------------------- | --------------------------------------------------------- | --------- |
| `obto_fetch_page`          | Fetch an HTML page record                                 | Read-only |
| `obto_fetch_javascript`    | Fetch a JavaScript/React module                           | Read-only |
| `obto_fetch_stylesheet`    | Fetch a CSS stylesheet                                    | Read-only |
| `obto_fetch_route`         | Fetch a route/API handler                                 | Read-only |
| `obto_fetch_server_script` | Fetch a backend server script                             | Read-only |
| `obto_fetch_client_script` | Fetch a frontend client script (OBTO app shell component) | Read-only |
| `obto_fetch_client_policy` | Fetch a client policy record                              | Read-only |
| `obto_fetch_ui_template`   | Fetch a UI template record                                | Read-only |

#### Discovery & Preview

| Tool                    | Description                                                                                                     | Type      |
| ----------------------- | --------------------------------------------------------------------------------------------------------------- | --------- |
| `obto_semantic_search`  | Perform semantic vector search across your codebase — finds where specific features, components, or logic lives | Read-only |
| `obto_generate_preview` | Generate a live preview URL for a specified application                                                         | Read-only |

***

### Tool Details

#### `obto_upsert_record`

This is the **workhorse tool** for deploying code to OBTO. It handles all collection types except routes.

**Parameters:**

| Parameter    | Type   | Required    | Description                                                                                                      |
| ------------ | ------ | ----------- | ---------------------------------------------------------------------------------------------------------------- |
| `collection` | string | ✅           | Target collection: `pltf_page`, `pltf_javascript`, `pltf_stylesheet`, `pltf_script_client`, `pltf_script_server` |
| `name`       | string | ✅           | Unique name for the artifact within the app                                                                      |
| `appName`    | string | ✅           | The application this artifact belongs to                                                                         |
| `script`     | string | ✅           | The code content (HTML, JavaScript, CSS, etc.)                                                                   |
| `host`       | string | Conditional | Required for browser-facing types: `pltf_page`, `pltf_javascript`, `pltf_stylesheet`. Format: `appname.obto.co`  |

**Which collection to use:**

| You want to deploy...             | Use collection       |
| --------------------------------- | -------------------- |
| An HTML entry page                | `pltf_page`          |
| A React module / frontend JS      | `pltf_javascript`    |
| A CSS stylesheet                  | `pltf_stylesheet`    |
| A backend Node.js class           | `pltf_script_server` |
| A native OBTO app shell component | `pltf_script_client` |

> ⚠️ **Routes use a different tool.** To create or update API routes, use `obto_create_route` or `obto_update_route` instead.

***

#### `obto_create_route`

Creates a new Express.js route (API endpoint) on the platform.

**Parameters:**

| Parameter     | Type    | Required | Description                                                                       |
| ------------- | ------- | -------- | --------------------------------------------------------------------------------- |
| `name`        | string  | ✅        | Unique name for the route                                                         |
| `appName`     | string  | ✅        | The application this route belongs to                                             |
| `method`      | enum    | ✅        | HTTP method: `get`, `post`, `put`, `delete`, `patch`                              |
| `path`        | string  | ✅        | URL path for the route (no leading slash)                                         |
| `script`      | string  | ✅        | Express.js handler code (Node.js)                                                 |
| `router`      | enum    | ✅        | Router context: `api`, `microservice`, `microservicev2`, `site`, `static`, `core` |
| `description` | string  | ✅        | Description of the route's purpose                                                |
| `secured`     | boolean | Optional | Whether the route requires authentication (default: `false`)                      |

**Example route script:**

```javascript
const svc = new xe.ContactService();
const result = await svc.save(req.body);
res.json({ success: true, data: result });
```

***

#### `obto_patch_artifact`

For small, surgical changes to existing code. Uses search & replace to modify a specific block without rewriting the entire file.

**Parameters:**

| Parameter       | Type   | Required | Description                                                                                                                  |
| --------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `appName`       | string | ✅        | The application name                                                                                                         |
| `artifactName`  | string | ✅        | Name of the artifact to patch                                                                                                |
| `artifactType`  | enum   | ✅        | Collection type: `pltf_script_client`, `pltf_script_server`, `pltf_route`, `pltf_page`, `pltf_javascript`, `pltf_stylesheet` |
| `searchString`  | string | ✅        | The exact code block to find                                                                                                 |
| `replaceString` | string | ✅        | The replacement code block                                                                                                   |

> ⚠️ **Single-line patches only.** If you need to replace a multi-line block, fetch the file, apply changes, and use `obto_upsert_record` to overwrite it.

***

#### `obto_semantic_search`

Finds code across your entire application using natural language queries. Powered by vector embeddings.

**Parameters:**

| Parameter | Type   | Required | Description                                                                |
| --------- | ------ | -------- | -------------------------------------------------------------------------- |
| `appName` | string | ✅        | The application to search within                                           |
| `query`   | string | ✅        | Natural language search query (e.g., "where is the header color defined?") |

**Example queries:**

* `"where is the contact form submission handled?"`
* `"find the user authentication logic"`
* `"which component renders the pricing table?"`

***

#### `obto_generate_preview`

Generates a live preview URL so you can see your app without publishing it publicly.

**Parameters:**

| Parameter | Type   | Required | Description                |
| --------- | ------ | -------- | -------------------------- |
| `appName` | string | ✅        | The application to preview |

**Returns:** A URL you can open in your browser to see the current state of the application.

***

### Deployment Order

When using these tools, always deploy in this order:

```
1. pltf_script_server  →  Backend logic (models, services)
2. pltf_route           →  API endpoints
3. pltf_stylesheet      →  CSS styles
4. pltf_javascript      →  React frontend modules
5. pltf_page            →  HTML entry points
```

**Why?** Frontend artifacts reference backend artifacts at runtime. If you deploy a page before its API route exists, the app will break on first load.

***

### Next Steps

* **Create Tool** — Build custom MCP tools for your specific workflows
* **Dev Zone** — Your development workspace


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.obto.co/ai/mcp-tools-out-of-the-box.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.