diff --git a/ai-tools/claude-code.mdx b/ai-tools/claude-code.mdx
deleted file mode 100644
index bdc4e04..0000000
--- a/ai-tools/claude-code.mdx
+++ /dev/null
@@ -1,76 +0,0 @@
----
-title: "Claude Code setup"
-description: "Configure Claude Code for your documentation workflow"
-icon: "asterisk"
----
-
-Claude Code is Anthropic's official CLI tool. This guide will help you set up Claude Code to help you write and maintain your documentation.
-
-## Prerequisites
-
-- Active Claude subscription (Pro, Max, or API access)
-
-## Setup
-
-1. Install Claude Code globally:
-
- ```bash
- npm install -g @anthropic-ai/claude-code
-```
-
-2. Navigate to your docs directory.
-3. (Optional) Add the `CLAUDE.md` file below to your project.
-4. Run `claude` to start.
-
-## Create `CLAUDE.md`
-
-Create a `CLAUDE.md` file at the root of your documentation repository to train Claude Code on your specific documentation standards:
-
-````markdown
-# Mintlify documentation
-
-## Working relationship
-- You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so
-- ALWAYS ask for clarification rather than making assumptions
-- NEVER lie, guess, or make up information
-
-## Project context
-- Format: MDX files with YAML frontmatter
-- Config: docs.json for navigation, theme, settings
-- Components: Mintlify components
-
-## Content strategy
-- Document just enough for user success - not too much, not too little
-- Prioritize accuracy and usability of information
-- Make content evergreen when possible
-- Search for existing information before adding new content. Avoid duplication unless it is done for a strategic reason
-- Check existing patterns for consistency
-- Start by making the smallest reasonable changes
-
-## Frontmatter requirements for pages
-- title: Clear, descriptive page title
-- description: Concise summary for SEO/navigation
-
-## Writing standards
-- Second-person voice ("you")
-- Prerequisites at start of procedural content
-- Test all code examples before publishing
-- Match style and formatting of existing pages
-- Include both basic and advanced use cases
-- Language tags on all code blocks
-- Alt text on all images
-- Relative paths for internal links
-
-## Git workflow
-- NEVER use --no-verify when committing
-- Ask how to handle uncommitted changes before starting
-- Create a new branch when no clear branch exists for changes
-- Commit frequently throughout development
-- NEVER skip or disable pre-commit hooks
-
-## Do not
-- Skip frontmatter on any MDX file
-- Use absolute URLs for internal links
-- Include untested code examples
-- Make assumptions - always ask for clarification
-````
diff --git a/ai-tools/cursor.mdx b/ai-tools/cursor.mdx
deleted file mode 100644
index fbb7761..0000000
--- a/ai-tools/cursor.mdx
+++ /dev/null
@@ -1,420 +0,0 @@
----
-title: "Cursor setup"
-description: "Configure Cursor for your documentation workflow"
-icon: "arrow-pointer"
----
-
-Use Cursor to help write and maintain your documentation. This guide shows how to configure Cursor for better results on technical writing tasks and using Mintlify components.
-
-## Prerequisites
-
-- Cursor editor installed
-- Access to your documentation repository
-
-## Project rules
-
-Create project rules that all team members can use. In your documentation repository root:
-
-```bash
-mkdir -p .cursor
-```
-
-Create `.cursor/rules.md`:
-
-````markdown
-# Mintlify technical writing rule
-
-You are an AI writing assistant specialized in creating exceptional technical documentation using Mintlify components and following industry-leading technical writing practices.
-
-## Core writing principles
-
-### Language and style requirements
-
-- Use clear, direct language appropriate for technical audiences
-- Write in second person ("you") for instructions and procedures
-- Use active voice over passive voice
-- Employ present tense for current states, future tense for outcomes
-- Avoid jargon unless necessary and define terms when first used
-- Maintain consistent terminology throughout all documentation
-- Keep sentences concise while providing necessary context
-- Use parallel structure in lists, headings, and procedures
-
-### Content organization standards
-
-- Lead with the most important information (inverted pyramid structure)
-- Use progressive disclosure: basic concepts before advanced ones
-- Break complex procedures into numbered steps
-- Include prerequisites and context before instructions
-- Provide expected outcomes for each major step
-- Use descriptive, keyword-rich headings for navigation and SEO
-- Group related information logically with clear section breaks
-
-### User-centered approach
-
-- Focus on user goals and outcomes rather than system features
-- Anticipate common questions and address them proactively
-- Include troubleshooting for likely failure points
-- Write for scannability with clear headings, lists, and white space
-- Include verification steps to confirm success
-
-## Mintlify component reference
-
-### Callout components
-
-#### Note - Additional helpful information
-
-
-Supplementary information that supports the main content without interrupting flow
-
-
-#### Tip - Best practices and pro tips
-
-
-Expert advice, shortcuts, or best practices that enhance user success
-
-
-#### Warning - Important cautions
-
-
-Critical information about potential issues, breaking changes, or destructive actions
-
-
-#### Info - Neutral contextual information
-
-
-Background information, context, or neutral announcements
-
-
-#### Check - Success confirmations
-
-
-Positive confirmations, successful completions, or achievement indicators
-
-
-### Code components
-
-#### Single code block
-
-Example of a single code block:
-
-```javascript config.js
-const apiConfig = {
- baseURL: 'https://api.example.com',
- timeout: 5000,
- headers: {
- 'Authorization': `Bearer ${process.env.API_TOKEN}`
- }
-};
-```
-
-#### Code group with multiple languages
-
-Example of a code group:
-
-
-```javascript Node.js
-const response = await fetch('/api/endpoint', {
- headers: { Authorization: `Bearer ${apiKey}` }
-});
-```
-
-```python Python
-import requests
-response = requests.get('/api/endpoint',
- headers={'Authorization': f'Bearer {api_key}'})
-```
-
-```curl cURL
-curl -X GET '/api/endpoint' \
- -H 'Authorization: Bearer YOUR_API_KEY'
-```
-
-
-#### Request/response examples
-
-Example of request/response documentation:
-
-
-```bash cURL
-curl -X POST 'https://api.example.com/users' \
- -H 'Content-Type: application/json' \
- -d '{"name": "John Doe", "email": "john@example.com"}'
-```
-
-
-
-```json Success
-{
- "id": "user_123",
- "name": "John Doe",
- "email": "john@example.com",
- "created_at": "2024-01-15T10:30:00Z"
-}
-```
-
-
-### Structural components
-
-#### Steps for procedures
-
-Example of step-by-step instructions:
-
-
-
- Run `npm install` to install required packages.
-
-
- Verify installation by running `npm list`.
-
-
-
-
- Create a `.env` file with your API credentials.
-
- ```bash
- API_KEY=your_api_key_here
- ```
-
-
- Never commit API keys to version control.
-
-
-
-
-#### Tabs for alternative content
-
-Example of tabbed content:
-
-
-
- ```bash
- brew install node
- npm install -g package-name
- ```
-
-
-
- ```powershell
- choco install nodejs
- npm install -g package-name
- ```
-
-
-
- ```bash
- sudo apt install nodejs npm
- npm install -g package-name
- ```
-
-
-
-#### Accordions for collapsible content
-
-Example of accordion groups:
-
-
-
- - **Firewall blocking**: Ensure ports 80 and 443 are open
- - **Proxy configuration**: Set HTTP_PROXY environment variable
- - **DNS resolution**: Try using 8.8.8.8 as DNS server
-
-
-
- ```javascript
- const config = {
- performance: { cache: true, timeout: 30000 },
- security: { encryption: 'AES-256' }
- };
- ```
-
-
-
-### Cards and columns for emphasizing information
-
-Example of cards and card groups:
-
-
-Complete walkthrough from installation to your first API call in under 10 minutes.
-
-
-
-
- Learn how to authenticate requests using API keys or JWT tokens.
-
-
-
- Understand rate limits and best practices for high-volume usage.
-
-
-
-### API documentation components
-
-#### Parameter fields
-
-Example of parameter documentation:
-
-
-Unique identifier for the user. Must be a valid UUID v4 format.
-
-
-
-User's email address. Must be valid and unique within the system.
-
-
-
-Maximum number of results to return. Range: 1-100.
-
-
-
-Bearer token for API authentication. Format: `Bearer YOUR_API_KEY`
-
-
-#### Response fields
-
-Example of response field documentation:
-
-
-Unique identifier assigned to the newly created user.
-
-
-
-ISO 8601 formatted timestamp of when the user was created.
-
-
-
-List of permission strings assigned to this user.
-
-
-#### Expandable nested fields
-
-Example of nested field documentation:
-
-
-Complete user object with all associated data.
-
-
-
- User profile information including personal details.
-
-
-
- User's first name as entered during registration.
-
-
-
- URL to user's profile picture. Returns null if no avatar is set.
-
-
-
-
-
-
-### Media and advanced components
-
-#### Frames for images
-
-Wrap all images in frames:
-
-
-
-
-
-
-
-
-
-#### Videos
-
-Use the HTML video element for self-hosted video content:
-
-
-
-Embed YouTube videos using iframe elements:
-
-
-
-#### Tooltips
-
-Example of tooltip usage:
-
-
-API
-
-
-#### Updates
-
-Use updates for changelogs:
-
-
-## New features
-- Added bulk user import functionality
-- Improved error messages with actionable suggestions
-
-## Bug fixes
-- Fixed pagination issue with large datasets
-- Resolved authentication timeout problems
-
-
-## Required page structure
-
-Every documentation page must begin with YAML frontmatter:
-
-```yaml
----
-title: "Clear, specific, keyword-rich title"
-description: "Concise description explaining page purpose and value"
----
-```
-
-## Content quality standards
-
-### Code examples requirements
-
-- Always include complete, runnable examples that users can copy and execute
-- Show proper error handling and edge case management
-- Use realistic data instead of placeholder values
-- Include expected outputs and results for verification
-- Test all code examples thoroughly before publishing
-- Specify language and include filename when relevant
-- Add explanatory comments for complex logic
-- Never include real API keys or secrets in code examples
-
-### API documentation requirements
-
-- Document all parameters including optional ones with clear descriptions
-- Show both success and error response examples with realistic data
-- Include rate limiting information with specific limits
-- Provide authentication examples showing proper format
-- Explain all HTTP status codes and error handling
-- Cover complete request/response cycles
-
-### Accessibility requirements
-
-- Include descriptive alt text for all images and diagrams
-- Use specific, actionable link text instead of "click here"
-- Ensure proper heading hierarchy starting with H2
-- Provide keyboard navigation considerations
-- Use sufficient color contrast in examples and visuals
-- Structure content for easy scanning with headers and lists
-
-## Component selection logic
-
-- Use **Steps** for procedures and sequential instructions
-- Use **Tabs** for platform-specific content or alternative approaches
-- Use **CodeGroup** when showing the same concept in multiple programming languages
-- Use **Accordions** for progressive disclosure of information
-- Use **RequestExample/ResponseExample** specifically for API endpoint documentation
-- Use **ParamField** for API parameters, **ResponseField** for API responses
-- Use **Expandable** for nested object properties or hierarchical information
-````
diff --git a/ai-tools/windsurf.mdx b/ai-tools/windsurf.mdx
deleted file mode 100644
index fce12bf..0000000
--- a/ai-tools/windsurf.mdx
+++ /dev/null
@@ -1,96 +0,0 @@
----
-title: "Windsurf setup"
-description: "Configure Windsurf for your documentation workflow"
-icon: "water"
----
-
-Configure Windsurf's Cascade AI assistant to help you write and maintain documentation. This guide shows how to set up Windsurf specifically for your Mintlify documentation workflow.
-
-## Prerequisites
-
-- Windsurf editor installed
-- Access to your documentation repository
-
-## Workspace rules
-
-Create workspace rules that provide Windsurf with context about your documentation project and standards.
-
-Create `.windsurf/rules.md` in your project root:
-
-````markdown
-# Mintlify technical writing rule
-
-## Project context
-
-- This is a documentation project on the Mintlify platform
-- We use MDX files with YAML frontmatter
-- Navigation is configured in `docs.json`
-- We follow technical writing best practices
-
-## Writing standards
-
-- Use second person ("you") for instructions
-- Write in active voice and present tense
-- Start procedures with prerequisites
-- Include expected outcomes for major steps
-- Use descriptive, keyword-rich headings
-- Keep sentences concise but informative
-
-## Required page structure
-
-Every page must start with frontmatter:
-
-```yaml
----
-title: "Clear, specific title"
-description: "Concise description for SEO and navigation"
----
-```
-
-## Mintlify components
-
-### Callouts
-
-- `` for helpful supplementary information
-- `` for important cautions and breaking changes
-- `` for best practices and expert advice
-- `` for neutral contextual information
-- `` for success confirmations
-
-### Code examples
-
-- When appropriate, include complete, runnable examples
-- Use `` for multiple language examples
-- Specify language tags on all code blocks
-- Include realistic data, not placeholders
-- Use `` and `` for API docs
-
-### Procedures
-
-- Use `` component for sequential instructions
-- Include verification steps with `` components when relevant
-- Break complex procedures into smaller steps
-
-### Content organization
-
-- Use `` for platform-specific content
-- Use `` for progressive disclosure
-- Use `` and `` for highlighting content
-- Wrap images in `` components with descriptive alt text
-
-## API documentation requirements
-
-- Document all parameters with ``
-- Show response structure with ``
-- Include both success and error examples
-- Use `` for nested object properties
-- Always include authentication examples
-
-## Quality standards
-
-- Test all code examples before publishing
-- Use relative paths for internal links
-- Include alt text for all images
-- Ensure proper heading hierarchy (start with h2)
-- Check existing patterns for consistency
-````
diff --git a/api-getting-started.mdx b/api-getting-started.mdx
new file mode 100644
index 0000000..519b6a8
--- /dev/null
+++ b/api-getting-started.mdx
@@ -0,0 +1,109 @@
+---
+title: "Getting Started with the API"
+description: "Learn how to use the Metorial API, get your API key, and make your first request"
+---
+
+Welcome to the Metorial API! This guide will help you quickly understand how to start using our API and make your first requests.
+
+
+**What you'll learn:**
+- How to use the Metorial API
+- How to get your API key
+- How to make your first API request
+
+**Recommended reading:**
+- [Deploying Your First MCP Server](/metorial-101-deploying)
+
+
+## What is the Metorial API?
+
+The Metorial API is a simple, user-friendly way to interact with Metorial's services. It uses standard web communication (REST) and always returns data in JSON format, making it easy to work with across different programming languages.
+
+## Before You Begin: Getting Your API Key
+
+To use the Metorial API, you'll need an API key. You can generate these in two types:
+
+**Publishable API Keys** (`metorial_pk_`):
+
+- Used for public data access
+- Safe to use in client-side code
+- Starts with `metorial_pk_`
+
+**Secret API Keys** (`metorial_sk_`):
+
+- Provides full project access
+- Must be kept private
+- Starts with `metorial_sk_`
+
+
+You can generate both publishable and secret API keys in your Metorial dashboard by navigating to **Developer** → **API Keys**.
+
+
+
+
+## Making Your First API Request
+
+When making a request, you'll always use this base URL:
+
+```
+https://api.metorial.com
+```
+
+To authenticate, include your API key in the request header:
+
+```http
+Authorization: Bearer metorial_pk_abc123
+```
+
+To get started, let's make a simple request to fetch a list of threads:
+
+```bash
+curl -X GET https://api.metorial.com/secrets \
+ -H "Authorization: Bearer metorial_pk_abc123"
+```
+
+## Client Libraries
+
+We make integration super easy with official SDKs for:
+
+
+
+ Use Metorial with JavaScript or TypeScript.
+
+
+ Use Metorial with Python.
+
+
+
+## Important Things to Know
+
+### Rate Limits
+
+We have some basic usage limits to keep things fair:
+
+- 1000 requests per IP every 10 seconds
+- Development environments: 100 requests per 10 minutes
+- Production environments: 5000 requests per 10 minutes
+
+### Handling Responses
+
+Our API uses standard HTTP response codes:
+
+- `200`: Success!
+- `400`: Something's wrong with your request
+- `401`: Invalid API key
+- `403`: Not enough permissions
+- `404`: Can't find what you're looking for
+- `429`: You've hit the rate limit
+
+### Pagination
+
+When fetching lists of items, we support pagination. Each response includes cursors to help you fetch more items easily.
+
+## Need More Help?
+
+Check out our full documentation or reach out to our support team. Happy coding!
+
+
+ Explore SDKs for easier integration.
+
diff --git a/api-reference/endpoint/create.mdx b/api-reference/endpoint/create.mdx
deleted file mode 100644
index f3b6a11..0000000
--- a/api-reference/endpoint/create.mdx
+++ /dev/null
@@ -1,5 +0,0 @@
----
-title: "Create Plant"
-openapi: "POST /plants"
-description: "This is how creation works"
----
\ No newline at end of file
diff --git a/api-reference/endpoint/delete.mdx b/api-reference/endpoint/delete.mdx
deleted file mode 100644
index 657dfc8..0000000
--- a/api-reference/endpoint/delete.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-title: 'Delete Plant'
-openapi: 'DELETE /plants/{id}'
----
diff --git a/api-reference/endpoint/get.mdx b/api-reference/endpoint/get.mdx
deleted file mode 100644
index 7d2310b..0000000
--- a/api-reference/endpoint/get.mdx
+++ /dev/null
@@ -1,5 +0,0 @@
----
-title: "Get Plants"
-openapi: "GET /plants"
-description: "Test whether getting plants works"
----
\ No newline at end of file
diff --git a/api-reference/endpoint/webhook.mdx b/api-reference/endpoint/webhook.mdx
deleted file mode 100644
index 3291340..0000000
--- a/api-reference/endpoint/webhook.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-title: 'New Plant'
-openapi: 'WEBHOOK /plant/webhook'
----
diff --git a/api-reference/introduction.mdx b/api-reference/introduction.mdx
deleted file mode 100644
index c835b78..0000000
--- a/api-reference/introduction.mdx
+++ /dev/null
@@ -1,33 +0,0 @@
----
-title: 'Introduction'
-description: 'Example section for showcasing API endpoints'
----
-
-
- If you're not looking to build API reference documentation, you can delete
- this section by removing the api-reference folder.
-
-
-## Welcome
-
-There are two ways to build API documentation: [OpenAPI](https://mintlify.com/docs/api-playground/openapi/setup) and [MDX components](https://mintlify.com/docs/api-playground/mdx/configuration). For the starter kit, we are using the following OpenAPI specification.
-
-
- View the OpenAPI specification file
-
-
-## Authentication
-
-All API endpoints are authenticated using Bearer tokens and picked up from the specification file.
-
-```json
-"security": [
- {
- "bearerAuth": []
- }
-]
-```
diff --git a/api-reference/openapi.json b/api-reference/openapi.json
deleted file mode 100644
index da5326e..0000000
--- a/api-reference/openapi.json
+++ /dev/null
@@ -1,217 +0,0 @@
-{
- "openapi": "3.1.0",
- "info": {
- "title": "OpenAPI Plant Store",
- "description": "A sample API that uses a plant store as an example to demonstrate features in the OpenAPI specification",
- "license": {
- "name": "MIT"
- },
- "version": "1.0.0"
- },
- "servers": [
- {
- "url": "http://sandbox.mintlify.com"
- }
- ],
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "paths": {
- "/plants": {
- "get": {
- "description": "Returns all plants from the system that the user has access to",
- "parameters": [
- {
- "name": "limit",
- "in": "query",
- "description": "The maximum number of results to return",
- "schema": {
- "type": "integer",
- "format": "int32"
- }
- }
- ],
- "responses": {
- "200": {
- "description": "Plant response",
- "content": {
- "application/json": {
- "schema": {
- "type": "array",
- "items": {
- "$ref": "#/components/schemas/Plant"
- }
- }
- }
- }
- },
- "400": {
- "description": "Unexpected error",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/Error"
- }
- }
- }
- }
- }
- },
- "post": {
- "description": "Creates a new plant in the store",
- "requestBody": {
- "description": "Plant to add to the store",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/NewPlant"
- }
- }
- },
- "required": true
- },
- "responses": {
- "200": {
- "description": "plant response",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/Plant"
- }
- }
- }
- },
- "400": {
- "description": "unexpected error",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/Error"
- }
- }
- }
- }
- }
- }
- },
- "/plants/{id}": {
- "delete": {
- "description": "Deletes a single plant based on the ID supplied",
- "parameters": [
- {
- "name": "id",
- "in": "path",
- "description": "ID of plant to delete",
- "required": true,
- "schema": {
- "type": "integer",
- "format": "int64"
- }
- }
- ],
- "responses": {
- "204": {
- "description": "Plant deleted",
- "content": {}
- },
- "400": {
- "description": "unexpected error",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/Error"
- }
- }
- }
- }
- }
- }
- }
- },
- "webhooks": {
- "/plant/webhook": {
- "post": {
- "description": "Information about a new plant added to the store",
- "requestBody": {
- "description": "Plant added to the store",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/NewPlant"
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "Return a 200 status to indicate that the data was received successfully"
- }
- }
- }
- }
- },
- "components": {
- "schemas": {
- "Plant": {
- "required": [
- "name"
- ],
- "type": "object",
- "properties": {
- "name": {
- "description": "The name of the plant",
- "type": "string"
- },
- "tag": {
- "description": "Tag to specify the type",
- "type": "string"
- }
- }
- },
- "NewPlant": {
- "allOf": [
- {
- "$ref": "#/components/schemas/Plant"
- },
- {
- "required": [
- "id"
- ],
- "type": "object",
- "properties": {
- "id": {
- "description": "Identification number of the plant",
- "type": "integer",
- "format": "int64"
- }
- }
- }
- ]
- },
- "Error": {
- "required": [
- "error",
- "message"
- ],
- "type": "object",
- "properties": {
- "error": {
- "type": "integer",
- "format": "int32"
- },
- "message": {
- "type": "string"
- }
- }
- }
- },
- "securitySchemes": {
- "bearerAuth": {
- "type": "http",
- "scheme": "bearer"
- }
- }
- }
-}
\ No newline at end of file
diff --git a/concepts-environments.mdx b/concepts-environments.mdx
new file mode 100644
index 0000000..fc34c3a
--- /dev/null
+++ b/concepts-environments.mdx
@@ -0,0 +1,93 @@
+---
+title: "Development vs Production Environments"
+description: "Metorial uses instances to separate your development and production environments, allowing you to test safely before deploying to production."
+---
+
+
+**What you'll learn:**
+- The difference between development and production instances
+- How to work across environments
+- Best practices for environment management
+
+**References:**
+- [Projects and Organizations](/concepts-projects-organizations)
+
+
+## Understanding Instances
+
+An **instance** represents an isolated environment within your project. Each instance has its own:
+
+- Server deployments
+- API keys
+- OAuth sessions
+- Logs and metrics
+
+
+Changes in one instance don't affect others, allowing you to test in isolation.
+
+
+## Instance Types
+
+### Development Instance
+
+Your default workspace for building and testing.
+
+### Production Instance
+
+Your live environment for real users and applications.
+
+## Working Across Environments
+
+### Switching Instances
+
+In the Metorial dashboard, use the instance dropdown in the navigation to switch between environments.
+
+### Separate API Keys
+
+Use different API keys for each instance:
+
+
+```typescript TypeScript
+// Development
+let devMetorial = new Metorial({
+ apiKey: process.env.METORIAL_DEV_KEY
+});
+
+// Production
+let prodMetorial = new Metorial({
+ apiKey: process.env.METORIAL_PROD_KEY
+});
+```
+
+```python Python
+import os
+from metorial import Metorial
+
+# Development
+dev_metorial = Metorial(api_key=os.getenv("METORIAL_DEV_KEY"))
+
+# Production
+prod_metorial = Metorial(api_key=os.getenv("METORIAL_PROD_KEY"))
+```
+
+
+
+**Best Practices**
+
+**Never share credentials**: Use separate API keys and OAuth apps for each environment.
+
+**Test before production**: Always test deployments in development before using in production.
+
+**Access control**: Limit production access to necessary team members.
+
+
+## What's Next?
+
+
+
+ Learn how to monitor your deployments.
+
+
+ Create your first deployment in development.
+
+
diff --git a/concepts-monitoring.mdx b/concepts-monitoring.mdx
new file mode 100644
index 0000000..56bddb5
--- /dev/null
+++ b/concepts-monitoring.mdx
@@ -0,0 +1,77 @@
+---
+title: "Monitoring and Observability"
+description: "Metorial provides monitoring tools to help you understand how your MCP servers are performing and debug issues."
+---
+
+
+**What you'll learn:**
+- How to view logs
+- How to debug issues
+
+**References:**
+- [Testing in Dashboard](/metorial-101-monitoring)
+
+
+## Viewing Logs
+
+Access logs for your deployments through the Metorial dashboard:
+
+1. Navigate to your deployment
+2. Select the **Logs** tab
+
+
+
+### Session Logs
+
+See details for each session:
+- Creation timestamp
+- Deployments used
+- Tool calls made
+- Any errors
+
+
+
+### Tool Call Details
+
+Expand individual tool calls to see:
+- Input parameters
+- Response data
+- Execution time
+- Error messages (if any)
+
+
+
+## Debugging Common Issues
+
+### Authentication Errors
+
+- Verify your API key is correct
+- Check that OAuth tokens haven't expired
+- Ensure deployment ID is valid
+
+### Tool Execution Errors
+
+- Verify tool parameters match the schema
+- Check for rate limiting from external services
+- Review error messages in logs
+
+
+**Getting Help**
+
+If you can't resolve an issue:
+
+1. **Export relevant logs** from the dashboard
+2. **Note deployment IDs** for affected deployments
+3. **Contact support** at support@metorial.com
+
+
+## What's Next?
+
+
+
+ Learn more about testing deployments.
+
+
+ Handle errors gracefully in your code.
+
+
diff --git a/concepts-projects-organizations.mdx b/concepts-projects-organizations.mdx
new file mode 100644
index 0000000..c56ffa5
--- /dev/null
+++ b/concepts-projects-organizations.mdx
@@ -0,0 +1,88 @@
+---
+title: "Projects and Organizations"
+description: "Organizations and projects help you structure your work in Metorial and manage access to resources."
+---
+
+
+**What you'll learn:**
+- How organizations and projects are structured
+- How to organize your deployments
+
+
+## Understanding the Hierarchy
+
+Metorial uses a hierarchy to organize your work:
+
+```
+Organization
+└── Project(s)
+ └── Instance(s)
+ └── Server Deployments
+ └── API Keys
+ └── OAuth Sessions
+```
+
+### Organizations
+
+An **organization** is your top-level workspace - typically representing your company, team, or personal account.
+
+### Projects
+
+A **project** is a container for related work - typically representing an application or product.
+
+### Instances
+
+An **instance** represents an environment within a project (e.g., Development, Production).
+
+## Creating Your Workspace
+
+
+
+ When you sign up, you'll create your first organization and project.
+
+
+ Create additional projects for different applications.
+
+ 
+
+
+
+## Using Different API Keys
+
+Projects are isolated - use different API keys for different projects:
+
+
+```typescript TypeScript
+// Project A
+let metorialA = new Metorial({
+ apiKey: process.env.METORIAL_PROJECT_A_KEY
+});
+
+// Project B
+let metorialB = new Metorial({
+ apiKey: process.env.METORIAL_PROJECT_B_KEY
+});
+```
+
+```python Python
+import os
+from metorial import Metorial
+
+# Project A
+metorial_a = Metorial(api_key=os.getenv("METORIAL_PROJECT_A_KEY"))
+
+# Project B
+metorial_b = Metorial(api_key=os.getenv("METORIAL_PROJECT_B_KEY"))
+```
+
+
+## What's Next?
+
+
+
+ Learn about development vs production instances.
+
+
+ Create deployments within your projects.
+
+
diff --git a/concepts-server-deployments.mdx b/concepts-server-deployments.mdx
new file mode 100644
index 0000000..02e756e
--- /dev/null
+++ b/concepts-server-deployments.mdx
@@ -0,0 +1,103 @@
+---
+title: "Server Deployments"
+description: "Server deployments are the core building blocks of Metorial. They define which integrations and tools your AI applications can access."
+---
+
+
+**What you'll learn:**
+- What server deployments are and how they work
+- The difference between servers and deployments
+- How to use deployments in your applications
+
+**References:**
+- [Deploy Your First Server](/metorial-101-deploying)
+- [Sessions Guide](/concepts-sessions)
+
+
+## Understanding the Concepts
+
+### MCP Servers vs Deployments
+
+**MCP Server**: A template or blueprint for an integration (e.g., "GitHub Integration", "Slack Bot", "Exa Search").
+
+**Server Deployment**: A configured, ready-to-use instance of a server with your specific credentials and settings.
+
+
+Think of it like this:
+- **Server** = Your Class template
+- **Deployment** = Your instance with a particular configuration
+
+
+### Why Deployments?
+
+Deployments allow you to:
+
+- **Configure once, use everywhere**: Set up credentials once and reuse across your applications
+- **Manage multiple instances**: Create separate deployments for dev and production
+- **Control access**: Different API keys and OAuth sessions per deployment
+
+## Types of Servers
+
+### Out-of-the-box servers
+
+Deploy pre-built servers from the Metorial catalog.
+
+**Configuration types**:
+- **API Key-based**: Provide your API credentials (Exa, Tavily)
+- **OAuth-based**: Users authorize access (Slack, GitHub, Google Calendar)
+
+### Custom Server Deployments
+
+Deploy your own MCP server code:
+
+- **Managed**: Metorial hosts and runs your code
+- **External**: Connect your self-hosted server
+- **Forked**: Clone and modify an existing server
+
+
+**Deployment IDs**
+
+Every deployment has a unique ID. You'll use this ID when:
+- Creating sessions with the SDK
+- Making API calls
+
+**Finding your deployment ID**: Go to the deployment details page and copy the ID.
+
+
+## Using Deployments in Code
+
+
+```typescript TypeScript
+await metorial.withProviderSession(
+ provider,
+ { serverDeployments: [{ serverDeploymentId: 'your-deployment-id' }] },
+ async ({ tools, closeSession }) => {
+ // Use tools
+ await closeSession();
+ }
+);
+```
+
+```python Python
+async def session_handler(session):
+ # Use session["tools"] and session["callTools"]
+ pass
+
+await metorial.with_provider_session(
+ MetorialAnthropic,
+ [{"serverDeploymentId": "your-deployment-id"}],
+ session_handler
+)
+```
+
+
+## What's Next?
+
+
+
+ Understand how sessions connect to deployments.
+
+
+ Set up OAuth-based deployments.
+
+
diff --git a/concepts-sessions.mdx b/concepts-sessions.mdx
new file mode 100644
index 0000000..46e3e10
--- /dev/null
+++ b/concepts-sessions.mdx
@@ -0,0 +1,215 @@
+---
+title: "Sessions"
+description: "Sessions are active connections between your application and MCP server deployments."
+---
+
+
+**What you'll learn:**
+- What sessions are and how they work
+- How to create and close sessions
+- Streaming mode for real-time responses
+- Using OAuth with sessions
+
+
+## What is a Session?
+
+A **session** is an active connection to one or more MCP server deployments. During a session, your AI application can:
+
+- Discover available tools
+- Execute tool calls
+- Handle OAuth-authenticated requests
+
+## Creating Sessions
+
+
+```typescript TypeScript
+import { Metorial } from 'metorial';
+import { metorialAiSdk } from '@metorial/ai-sdk';
+
+let metorial = new Metorial({ apiKey: process.env.METORIAL_API_KEY });
+
+await metorial.withProviderSession(
+ metorialAiSdk,
+ {
+ serverDeployments: [
+ { serverDeploymentId: 'your-deployment-id' }
+ ]
+ },
+ async ({ tools, callTools, closeSession }) => {
+ // tools: Array of tools formatted for your provider
+ // callTools: Function to execute tool calls
+ // closeSession: Function to close the session
+
+ await closeSession();
+ }
+);
+```
+
+```python Python
+import os
+from metorial import Metorial, MetorialAnthropic
+
+metorial = Metorial(api_key=os.getenv("METORIAL_API_KEY"))
+
+async def session_handler(session):
+ # session["tools"]: List of tools
+ # session["callTools"]: Function to execute tool calls
+ pass
+
+await metorial.with_provider_session(
+ MetorialAnthropic,
+ [{"serverDeploymentId": "your-deployment-id"}],
+ session_handler
+)
+```
+
+
+## Session Options
+
+### Streaming Mode
+
+Enable streaming for real-time AI responses:
+
+
+```typescript TypeScript
+import { Metorial } from 'metorial';
+import { metorialAiSdk } from '@metorial/ai-sdk';
+import { anthropic } from '@ai-sdk/anthropic';
+import { streamText } from 'ai';
+
+let metorial = new Metorial({ apiKey: process.env.METORIAL_API_KEY });
+
+await metorial.withProviderSession(
+ metorialAiSdk,
+ {
+ serverDeployments: [
+ { serverDeploymentId: 'your-deployment-id' }
+ ],
+ streaming: true
+ },
+ async ({ tools, closeSession }) => {
+ let result = streamText({
+ model: anthropic('claude-sonnet-4-5'),
+ prompt: 'Your prompt',
+ tools: tools,
+ onFinish: async () => await closeSession()
+ });
+
+ for await (let text of result.textStream) {
+ process.stdout.write(text);
+ }
+ }
+);
+```
+
+```python Python
+import os
+from metorial import Metorial, MetorialAnthropic
+from anthropic import AsyncAnthropic
+
+metorial = Metorial(api_key=os.getenv("METORIAL_API_KEY"))
+anthropic = AsyncAnthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
+
+async def session_handler(session):
+ async with anthropic.messages.stream(
+ model="claude-sonnet-4-20250514",
+ max_tokens=1024,
+ messages=[{"role": "user", "content": "Your prompt"}],
+ tools=session["tools"]
+ ) as stream:
+ async for text in stream.text_stream:
+ print(text, end="", flush=True)
+
+await metorial.with_provider_session(
+ MetorialAnthropic,
+ [{"serverDeploymentId": "your-deployment-id"}],
+ session_handler
+)
+```
+
+
+### With OAuth
+
+Include OAuth session for authenticated integrations:
+
+
+```typescript TypeScript
+{
+ serverDeployments: [
+ {
+ serverDeploymentId: 'slack-deployment',
+ oauthSessionId: 'oauth_abc123'
+ }
+ ]
+}
+```
+
+```python Python
+[
+ {
+ "serverDeploymentId": "slack-deployment",
+ "oauthSessionId": "oauth_abc123"
+ }
+]
+```
+
+
+### Multiple Deployments
+
+Combine tools from multiple deployments in one session:
+
+
+```typescript TypeScript
+{
+ serverDeployments: [
+ { serverDeploymentId: 'github-deployment' },
+ { serverDeploymentId: 'slack-deployment' },
+ { serverDeploymentId: 'exa-deployment' }
+ ]
+}
+```
+
+```python Python
+[
+ {"serverDeploymentId": "github-deployment"},
+ {"serverDeploymentId": "slack-deployment"},
+ {"serverDeploymentId": "exa-deployment"}
+]
+```
+
+
+## Closing Sessions
+
+Always close your session when done to free up resources:
+
+
+```typescript TypeScript
+async ({ tools, closeSession }) => {
+ try {
+ // Your code
+ } finally {
+ await closeSession(); // Always called
+ }
+}
+```
+
+```python Python
+async def session_handler(session):
+ try:
+ # Your code
+ pass
+ finally:
+ await session["closeSession"]() # Always called
+```
+
+
+## What's Next?
+
+
+
+ Handle OAuth sessions for authenticated integrations.
+
+
+ Use sessions with OpenAI, Anthropic, Google, and more.
+
+
diff --git a/custom-servers-external-authentication.mdx b/custom-servers-external-authentication.mdx
new file mode 100644
index 0000000..47e2cab
--- /dev/null
+++ b/custom-servers-external-authentication.mdx
@@ -0,0 +1,27 @@
+---
+title: "External Server Authentication"
+description: "Secure your external MCP server connections."
+---
+
+
+**What you'll learn:**
+- Authentication methods
+- Security best practices
+
+
+Secure your external server with bearer token authentication. Metorial sends a token with every request that your server must validate before processing.
+
+## Authentication Token
+
+Metorial provides a unique bearer token when you register your external server. Include this token validation in your server's request handling code. Check the Authorization header on every incoming request and reject any requests without a valid token.
+
+## HTTPS Required
+
+External servers must use HTTPS for all connections. This encrypts traffic between Metorial and your server, protecting sensitive data and authentication tokens.
+
+
+**Security Requirements:**
+- HTTPS required for production
+- Self-signed certificates not supported
+- Valid SSL certificate needed
+
diff --git a/custom-servers-external-connecting.mdx b/custom-servers-external-connecting.mdx
new file mode 100644
index 0000000..c640eb5
--- /dev/null
+++ b/custom-servers-external-connecting.mdx
@@ -0,0 +1,51 @@
+---
+title: "Connecting External Servers"
+description: "Connect your self-hosted MCP server to Metorial."
+---
+
+
+**What you'll learn:**
+- How external servers work
+- Connection requirements
+- Security
+
+
+External servers run on your own infrastructure and connect to Metorial via HTTP/HTTPS. You maintain complete control over hosting, deployment, and security while using Metorial for tool distribution.
+
+## External Server Requirements
+
+Your server must meet these requirements to connect to Metorial:
+
+
+**Requirements:**
+- HTTP/HTTPS endpoint that Metorial can reach
+- MCP protocol implementation
+- Bearer token authentication
+- HTTPS required for production
+
+
+## Registering External Server
+
+
+
+ Enter your server's URL in the Metorial dashboard.
+ 
+
+
+ Metorial generates a unique authentication token.
+
+
+ Add token validation to your server's request handler.
+
+
+ Create a deployment that connects to your external server.
+
+
+
+## What's Next?
+
+
+
+ Learn how to secure your external server connections.
+
+
diff --git a/custom-servers-forking-customizing.mdx b/custom-servers-forking-customizing.mdx
new file mode 100644
index 0000000..0f9bc46
--- /dev/null
+++ b/custom-servers-forking-customizing.mdx
@@ -0,0 +1,60 @@
+---
+title: "Customizing Forked Servers"
+description: "Modify forked servers to meet your needs."
+---
+
+
+**What you'll learn:**
+- How to edit forked code
+- Adding new tools
+- Testing changes
+
+
+Edit your forked server's code to customize tools, add new functionality, or integrate with your systems. Changes are deployed as a managed server.
+
+## Editing Forked Code
+
+
+
+ Open the code editor from your forked server's dashboard.
+
+
+ Modify any file with syntax highlighting and autocomplete.
+
+
+ Changes save automatically as you edit.
+
+
+ Test your changes in the editor before deploying.
+
+
+
+## Adding Tools
+
+Define new tools by adding tool definitions and handler functions to your forked code. Tools follow the MCP specification with a schema defining inputs and a function implementing the logic.
+
+
+**Tool Structure:**
+- Schema: Defines tool inputs and outputs
+- Handler: Implements the tool logic
+- Registration: Adds tool to your server
+
+
+Modify existing tools by editing their handler functions or input schemas.
+
+## Deploy Changes
+
+
+
+ Check your code modifications in the editor.
+
+
+ Deploy your customized server.
+
+
+ Metorial packages your changes and runs tests.
+
+
+ Your custom tools become available through the SDK.
+
+
diff --git a/custom-servers-forking-overview.mdx b/custom-servers-forking-overview.mdx
new file mode 100644
index 0000000..327de9d
--- /dev/null
+++ b/custom-servers-forking-overview.mdx
@@ -0,0 +1,50 @@
+---
+title: "Forking MCP Servers"
+description: "Clone and customize existing integrations."
+---
+
+
+**What you'll learn:**
+- What forking is
+- How to fork servers
+- Customization
+
+
+Forking creates your own copy of an existing integration from the Metorial catalog. Start with a working server and customize the code to add features, modify behavior, or integrate with your systems.
+
+## What is Forking?
+
+Forking duplicates an integration's complete source code into your account. Your forked server is independent from the original and becomes a managed server that you control. Make any changes you want without affecting the original integration.
+
+
+**Benefits of Forking:**
+- Start with a working implementation
+- Customize to your specific needs
+- No impact on the original integration
+- Deploy as your own managed server
+
+
+## How to Fork
+
+
+
+ Browse the Metorial catalog for a server you want to customize.
+
+
+ Click the "Fork" button on the integration page.
+
+
+ Access the code editor to modify your forked server.
+
+
+ Deploy your customized version as a managed server.
+
+
+
+## What's Next?
+
+
+
+ Learn how to modify your forked server.
+
+
diff --git a/custom-servers-managed-configuration.mdx b/custom-servers-managed-configuration.mdx
new file mode 100644
index 0000000..c0ca89a
--- /dev/null
+++ b/custom-servers-managed-configuration.mdx
@@ -0,0 +1,36 @@
+---
+title: "Configuring Managed Servers"
+description: "Configure environment variables, resource limits, and server settings."
+---
+
+
+**What you'll learn:**
+- Environment variables
+- Resource limits
+- Build configuration
+
+
+Configure your managed server's runtime behavior through environment variables and resource limits. These settings control how your server runs and how much resources it can use.
+
+## Environment Variables
+
+Set sensitive configuration in server's **Settings** → **Properties** section.
+
+
+
+## Resource Limits
+
+Set memory, timeout, and concurrency limits for your server.
+
+
+**Resource Settings:**
+- **Memory**: Controls how much RAM your server can use
+- **Timeout**: Defines how long a single request can run
+- **Concurrency**: Maximum number of simultaneous requests
+
+
+## What's Next?
+
+
+ Learn about deploying and managing versions.
+
diff --git a/custom-servers-managed-deployment.mdx b/custom-servers-managed-deployment.mdx
new file mode 100644
index 0000000..d67b8be
--- /dev/null
+++ b/custom-servers-managed-deployment.mdx
@@ -0,0 +1,51 @@
+---
+title: "Deploying Managed Servers"
+description: "Learn how to deploy and manage versions of your custom MCP servers."
+---
+
+
+**What you'll learn:**
+- How deployments work
+- Version management
+- Rollback strategies
+
+
+Deploy your managed server code and manage different versions over time. Metorial automatically builds and deploys your code when you upload it.
+
+## Creating Deployments
+
+
+
+ Upload your server code through the dashboard.
+
+
+ Metorial builds your server and installs dependencies automatically.
+
+
+ The build process validates your code and reports any errors.
+
+
+ Your server deploys and becomes available for use.
+
+
+
+## Version Management
+
+Each deployment creates a new version with a unique version number. View all versions in the dashboard, including deployment timestamps and the code changes in each version. You can switch between versions at any time.
+
+
+**Version History:**
+- Every deployment is preserved
+- View timestamps and changes
+- Switch between versions instantly
+
+
+## Rolling Back
+
+Revert to any previous version if you encounter issues with a new deployment. Select the version you want to restore and click Deploy. Rolling back is instant and doesn't require rebuilding your code.
+
+## What's Next?
+
+
+ Configure your server settings.
+
diff --git a/custom-servers-managed-getting-started.mdx b/custom-servers-managed-getting-started.mdx
new file mode 100644
index 0000000..670b2e3
--- /dev/null
+++ b/custom-servers-managed-getting-started.mdx
@@ -0,0 +1,62 @@
+---
+title: "Getting Started with Managed Servers"
+description: "Deploy custom MCP server code without managing infrastructure."
+---
+
+
+**What you'll learn:**
+- How to create a managed server
+- Supported languages
+
+
+Managed servers let you deploy custom MCP server code without managing infrastructure. Upload your code and Metorial handles hosting, scaling, and deployment.
+
+## Supported Languages
+
+Metorial supports two languages for managed servers:
+
+
+**TypeScript/JavaScript (Node.js)**
+- Full npm package support
+- Automatic TypeScript compilation
+- Node.js 18+ runtime
+
+
+
+**Python**
+- Standard Python packages with pip
+- Python 3.10+ runtime
+- Support for async/await
+
+
+## Creating a Managed Server
+
+
+
+ Go to **Gateway** → **Managed Servers**.
+
+ 
+
+
+ Click **Created Managed Server** and select **Managed Server**.
+
+ 
+
+
+ Upload your MCP server code.
+
+
+ Click **Deploy** and wait for the build to complete.
+
+
+
+## What's Next?
+
+
+
+ Configure environment variables and resource limits.
+
+
+ Learn about versions and deployments.
+
+
diff --git a/custom-servers-overview.mdx b/custom-servers-overview.mdx
new file mode 100644
index 0000000..becdf0e
--- /dev/null
+++ b/custom-servers-overview.mdx
@@ -0,0 +1,61 @@
+---
+title: "Custom MCP Servers"
+description: "Deploy your own custom MCP servers beyond the pre-built integrations."
+---
+
+
+**What you'll learn:**
+- The types of custom servers available
+- When to use each type
+
+
+Beyond the pre-built integrations in the Metorial catalog, you can deploy your own custom MCP servers. Choose from three deployment options based on your requirements.
+
+## Types of Custom Servers
+
+### Managed Servers
+
+Upload your MCP server code and Metorial hosts it for you. Your code runs in Metorial's infrastructure with automatic scaling and monitoring. Supported languages include TypeScript/JavaScript (Node.js) and Python.
+
+
+**Best for:**
+- Custom business logic and internal APIs
+- Teams that want to focus on code rather than infrastructure
+- Rapid prototyping and deployment
+
+
+### External Servers
+
+Connect your self-hosted MCP server to Metorial. Your server runs on your own infrastructure and Metorial connects to it via HTTP/HTTPS. You maintain full control over hosting, security, and deployment.
+
+
+**Best for:**
+- On-premises requirements
+- Existing infrastructure you want to integrate
+- Sensitive data that must stay in your environment
+
+
+### Forking
+
+Clone and modify an existing integration from the catalog. Start with a working integration and customize it to your needs. The forked server becomes a managed server that you can deploy and update.
+
+
+**Best for:**
+- Customizing existing integrations
+- Adding features to catalog servers
+- Learning from existing implementations
+
+
+## Getting Started
+
+
+
+ Deploy code hosted by Metorial.
+
+
+ Connect your self-hosted server.
+
+
+ Customize an existing integration.
+
+
diff --git a/development.mdx b/development.mdx
deleted file mode 100644
index ac633ba..0000000
--- a/development.mdx
+++ /dev/null
@@ -1,94 +0,0 @@
----
-title: 'Development'
-description: 'Preview changes locally to update your docs'
----
-
-
- **Prerequisites**:
- - Node.js version 19 or higher
- - A docs repository with a `docs.json` file
-
-
-Follow these steps to install and run Mintlify on your operating system.
-
-
-
-
-```bash
-npm i -g mint
-```
-
-
-
-
-Navigate to your docs directory where your `docs.json` file is located, and run the following command:
-
-```bash
-mint dev
-```
-
-A local preview of your documentation will be available at `http://localhost:3000`.
-
-
-
-
-## Custom ports
-
-By default, Mintlify uses port 3000. You can customize the port Mintlify runs on by using the `--port` flag. For example, to run Mintlify on port 3333, use this command:
-
-```bash
-mint dev --port 3333
-```
-
-If you attempt to run Mintlify on a port that's already in use, it will use the next available port:
-
-```md
-Port 3000 is already in use. Trying 3001 instead.
-```
-
-## Mintlify versions
-
-Please note that each CLI release is associated with a specific version of Mintlify. If your local preview does not align with the production version, please update the CLI:
-
-```bash
-npm mint update
-```
-
-## Validating links
-
-The CLI can assist with validating links in your documentation. To identify any broken links, use the following command:
-
-```bash
-mint broken-links
-```
-
-## Deployment
-
-If the deployment is successful, you should see the following:
-
-
-
-
-
-## Code formatting
-
-We suggest using extensions on your IDE to recognize and format MDX. If you're a VSCode user, consider the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting.
-
-## Troubleshooting
-
-
-
-
- This may be due to an outdated version of node. Try the following:
- 1. Remove the currently-installed version of the CLI: `npm remove -g mint`
- 2. Upgrade to Node v19 or higher.
- 3. Reinstall the CLI: `npm i -g mint`
-
-
-
-
- Solution: Go to the root of your device and delete the `~/.mintlify` folder. Then run `mint dev` again.
-
-
-
-Curious about what changed in the latest CLI version? Check out the [CLI changelog](https://www.npmjs.com/package/mintlify?activeTab=versions).
diff --git a/docs.json b/docs.json
index 46b44cc..4355fbe 100644
--- a/docs.json
+++ b/docs.json
@@ -1,68 +1,137 @@
{
"$schema": "https://mintlify.com/docs.json",
+ "name": "Metorial Documentation",
"theme": "mint",
- "name": "Mint Starter Kit",
+ "defaultColorMode": "light",
"colors": {
- "primary": "#16A34A",
- "light": "#07C983",
- "dark": "#15803D"
+ "primary": "#0099ff",
+ "light": "#4eb8ff",
+ "dark": "#006ab1"
+ },
+ "font": {
+ "headings": "Inter",
+ "body": "Inter",
+ "code": "JetBrains Mono"
},
"favicon": "/favicon.svg",
+ "logo": {
+ "light": "/logo/light.svg",
+ "dark": "/logo/dark.svg"
+ },
"navigation": {
"tabs": [
{
- "tab": "Guides",
+ "tab": "Getting Started",
"groups": [
{
- "group": "Getting started",
+ "group": "Metorial 101",
"pages": [
"index",
- "quickstart",
- "development"
+ "metorial-101-introduction",
+ "metorial-101-deploying",
+ "metorial-101-testing",
+ "metorial-101-using",
+ "metorial-101-monitoring"
+ ]
+ },
+ {
+ "group": "API",
+ "pages": [
+ "api-getting-started"
+ ]
+ }
+ ]
+ },
+ {
+ "tab": "Concepts",
+ "groups": [
+ {
+ "group": "Core Concepts",
+ "pages": [
+ "concepts-projects-organizations",
+ "concepts-server-deployments",
+ "concepts-sessions",
+ "concepts-environments",
+ "concepts-monitoring"
+ ]
+ }
+ ]
+ },
+ {
+ "tab": "Custom Servers",
+ "groups": [
+ {
+ "group": "Overview",
+ "pages": [
+ "custom-servers-overview"
]
},
{
- "group": "Customization",
+ "group": "Managed Servers",
"pages": [
- "essentials/settings",
- "essentials/navigation"
+ "custom-servers-managed-getting-started",
+ "custom-servers-managed-configuration",
+ "custom-servers-managed-deployment"
]
},
{
- "group": "Writing content",
+ "group": "External Servers",
+ "pages": [
+ "custom-servers-external-connecting",
+ "custom-servers-external-authentication"
+ ]
+ },
+ {
+ "group": "Forked Servers",
+ "pages": [
+ "custom-servers-forking-overview",
+ "custom-servers-forking-customizing"
+ ]
+ }
+ ]
+ },
+ {
+ "tab": "Integrations",
+ "groups": [
+ {
+ "group": "Overview",
"pages": [
- "essentials/markdown",
- "essentials/code",
- "essentials/images",
- "essentials/reusable-snippets"
+ "integrations-overview",
+ "integrations-browsing-catalog"
]
},
{
- "group": "AI tools",
+ "group": "Setup Guides",
"pages": [
- "ai-tools/cursor",
- "ai-tools/claude-code",
- "ai-tools/windsurf"
+ "integrations-api-key",
+ "integrations-oauth",
+ "integrations-enterprise-byo"
]
}
]
},
{
- "tab": "API reference",
+ "tab": "SDK",
"groups": [
{
- "group": "API documentation",
+ "group": "Getting Started",
"pages": [
- "api-reference/introduction"
+ "sdk-quickstart",
+ "sdk-javascript",
+ "sdk-python",
+ "sdk-oauth",
+ "sdk-error-handling"
]
},
{
- "group": "Endpoint examples",
+ "group": "Providers",
"pages": [
- "api-reference/endpoint/get",
- "api-reference/endpoint/create",
- "api-reference/endpoint/delete",
- "api-reference/endpoint/webhook"
+ "sdk-providers-overview",
+ "sdk-providers-ai-sdk",
+ "sdk-providers-openai",
+ "sdk-providers-anthropic",
+ "sdk-providers-google",
+ "sdk-providers-openai-compatible"
]
}
]
@@ -71,52 +140,54 @@
"global": {
"anchors": [
{
- "anchor": "Documentation",
- "href": "https://mintlify.com/docs",
- "icon": "book-open-cover"
+ "anchor": "Dashboard",
+ "href": "https://app.metorial.com",
+ "icon": "square-terminal"
+ },
+ {
+ "anchor": "Status",
+ "href": "https://status.metorial.com",
+ "icon": "circle-check"
},
{
- "anchor": "Blog",
- "href": "https://mintlify.com/blog",
- "icon": "newspaper"
+ "anchor": "GitHub",
+ "href": "https://github.com/metorial",
+ "icon": "github"
}
]
}
},
- "logo": {
- "light": "/logo/light.svg",
- "dark": "/logo/dark.svg"
- },
"navbar": {
"links": [
{
"label": "Support",
- "href": "mailto:hi@mintlify.com"
+ "href": "mailto:support@metorial.com"
}
],
"primary": {
"type": "button",
"label": "Dashboard",
- "href": "https://dashboard.mintlify.com"
+ "href": "https://app.metorial.com",
+ "color": "#0099ff"
}
},
+ "ai": {
+ "enabled": true,
+ "instructions": "You are a helpful assistant for Metorial documentation. Metorial is a platform for deploying and managing MCP (Model Context Protocol) servers. When answering questions, always cite specific documentation pages when possible. If you're unsure about something, direct users to the relevant documentation section or support at support@metorial.com."
+ },
"contextual": {
"options": [
- "copy",
- "view",
- "chatgpt",
- "claude",
- "perplexity",
- "mcp",
- "cursor",
- "vscode"
- ]
+ "copy",
+ "view",
+ "chatgpt",
+ "claude",
+ "cursor"
+ ]
},
"footer": {
"socials": {
- "x": "https://x.com/mintlify",
- "github": "https://github.com/mintlify",
- "linkedin": "https://linkedin.com/company/mintlify"
+ "github": "https://github.com/metorial",
+ "x": "https://x.com/MetorialAi"
}
}
}
diff --git a/essentials/code.mdx b/essentials/code.mdx
deleted file mode 100644
index ae2abbf..0000000
--- a/essentials/code.mdx
+++ /dev/null
@@ -1,35 +0,0 @@
----
-title: 'Code blocks'
-description: 'Display inline code and code blocks'
-icon: 'code'
----
-
-## Inline code
-
-To denote a `word` or `phrase` as code, enclose it in backticks (`).
-
-```
-To denote a `word` or `phrase` as code, enclose it in backticks (`).
-```
-
-## Code blocks
-
-Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks and follow the leading ticks with the programming language of your snippet to get syntax highlighting. Optionally, you can also write the name of your code after the programming language.
-
-```java HelloWorld.java
-class HelloWorld {
- public static void main(String[] args) {
- System.out.println("Hello, World!");
- }
-}
-```
-
-````md
-```java HelloWorld.java
-class HelloWorld {
- public static void main(String[] args) {
- System.out.println("Hello, World!");
- }
-}
-```
-````
diff --git a/essentials/images.mdx b/essentials/images.mdx
deleted file mode 100644
index 1144eb2..0000000
--- a/essentials/images.mdx
+++ /dev/null
@@ -1,59 +0,0 @@
----
-title: 'Images and embeds'
-description: 'Add image, video, and other HTML elements'
-icon: 'image'
----
-
-
-
-## Image
-
-### Using Markdown
-
-The [markdown syntax](https://www.markdownguide.org/basic-syntax/#images) lets you add images using the following code
-
-```md
-
-```
-
-Note that the image file size must be less than 5MB. Otherwise, we recommend hosting on a service like [Cloudinary](https://cloudinary.com/) or [S3](https://aws.amazon.com/s3/). You can then use that URL and embed.
-
-### Using embeds
-
-To get more customizability with images, you can also use [embeds](/writing-content/embed) to add images
-
-```html
-
-```
-
-## Embeds and HTML elements
-
-
-
-
-
-
-
-Mintlify supports [HTML tags in Markdown](https://www.markdownguide.org/basic-syntax/#html). This is helpful if you prefer HTML tags to Markdown syntax, and lets you create documentation with infinite flexibility.
-
-
-
-### iFrames
-
-Loads another HTML page within the document. Most commonly used for embedding videos.
-
-```html
-
-```
diff --git a/essentials/markdown.mdx b/essentials/markdown.mdx
deleted file mode 100644
index a45c1d5..0000000
--- a/essentials/markdown.mdx
+++ /dev/null
@@ -1,88 +0,0 @@
----
-title: 'Markdown syntax'
-description: 'Text, title, and styling in standard markdown'
-icon: 'text-size'
----
-
-## Titles
-
-Best used for section headers.
-
-```md
-## Titles
-```
-
-### Subtitles
-
-Best used for subsection headers.
-
-```md
-### Subtitles
-```
-
-
-
-Each **title** and **subtitle** creates an anchor and also shows up on the table of contents on the right.
-
-
-
-## Text formatting
-
-We support most markdown formatting. Simply add `**`, `_`, or `~` around text to format it.
-
-| Style | How to write it | Result |
-| ------------- | ----------------- | --------------- |
-| Bold | `**bold**` | **bold** |
-| Italic | `_italic_` | _italic_ |
-| Strikethrough | `~strikethrough~` | ~strikethrough~ |
-
-You can combine these. For example, write `**_bold and italic_**` to get **_bold and italic_** text.
-
-You need to use HTML to write superscript and subscript text. That is, add `` or `` around your text.
-
-| Text Size | How to write it | Result |
-| ----------- | ------------------------ | ---------------------- |
-| Superscript | `superscript` | superscript |
-| Subscript | `subscript` | subscript |
-
-## Linking to pages
-
-You can add a link by wrapping text in `[]()`. You would write `[link to google](https://google.com)` to [link to google](https://google.com).
-
-Links to pages in your docs need to be root-relative. Basically, you should include the entire folder path. For example, `[link to text](/writing-content/text)` links to the page "Text" in our components section.
-
-Relative links like `[link to text](../text)` will open slower because we cannot optimize them as easily.
-
-## Blockquotes
-
-### Singleline
-
-To create a blockquote, add a `>` in front of a paragraph.
-
-> Dorothy followed her through many of the beautiful rooms in her castle.
-
-```md
-> Dorothy followed her through many of the beautiful rooms in her castle.
-```
-
-### Multiline
-
-> Dorothy followed her through many of the beautiful rooms in her castle.
->
-> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
-
-```md
-> Dorothy followed her through many of the beautiful rooms in her castle.
->
-> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
-```
-
-### LaTeX
-
-Mintlify supports [LaTeX](https://www.latex-project.org) through the Latex component.
-
-8 x (vk x H1 - H2) = (0,1)
-
-```md
-8 x (vk x H1 - H2) = (0,1)
-```
diff --git a/essentials/navigation.mdx b/essentials/navigation.mdx
deleted file mode 100644
index 60adeff..0000000
--- a/essentials/navigation.mdx
+++ /dev/null
@@ -1,87 +0,0 @@
----
-title: 'Navigation'
-description: 'The navigation field in docs.json defines the pages that go in the navigation menu'
-icon: 'map'
----
-
-The navigation menu is the list of links on every website.
-
-You will likely update `docs.json` every time you add a new page. Pages do not show up automatically.
-
-## Navigation syntax
-
-Our navigation syntax is recursive which means you can make nested navigation groups. You don't need to include `.mdx` in page names.
-
-
-
-```json Regular Navigation
-"navigation": {
- "tabs": [
- {
- "tab": "Docs",
- "groups": [
- {
- "group": "Getting Started",
- "pages": ["quickstart"]
- }
- ]
- }
- ]
-}
-```
-
-```json Nested Navigation
-"navigation": {
- "tabs": [
- {
- "tab": "Docs",
- "groups": [
- {
- "group": "Getting Started",
- "pages": [
- "quickstart",
- {
- "group": "Nested Reference Pages",
- "pages": ["nested-reference-page"]
- }
- ]
- }
- ]
- }
- ]
-}
-```
-
-
-
-## Folders
-
-Simply put your MDX files in folders and update the paths in `docs.json`.
-
-For example, to have a page at `https://yoursite.com/your-folder/your-page` you would make a folder called `your-folder` containing an MDX file called `your-page.mdx`.
-
-
-
-You cannot use `api` for the name of a folder unless you nest it inside another folder. Mintlify uses Next.js which reserves the top-level `api` folder for internal server calls. A folder name such as `api-reference` would be accepted.
-
-
-
-```json Navigation With Folder
-"navigation": {
- "tabs": [
- {
- "tab": "Docs",
- "groups": [
- {
- "group": "Group Name",
- "pages": ["your-folder/your-page"]
- }
- ]
- }
- ]
-}
-```
-
-## Hidden pages
-
-MDX files not included in `docs.json` will not show up in the sidebar but are accessible through the search bar and by linking directly to them.
diff --git a/essentials/reusable-snippets.mdx b/essentials/reusable-snippets.mdx
deleted file mode 100644
index 376e27b..0000000
--- a/essentials/reusable-snippets.mdx
+++ /dev/null
@@ -1,110 +0,0 @@
----
-title: "Reusable snippets"
-description: "Reusable, custom snippets to keep content in sync"
-icon: "recycle"
----
-
-import SnippetIntro from '/snippets/snippet-intro.mdx';
-
-
-
-## Creating a custom snippet
-
-**Pre-condition**: You must create your snippet file in the `snippets` directory.
-
-
- Any page in the `snippets` directory will be treated as a snippet and will not
- be rendered into a standalone page. If you want to create a standalone page
- from the snippet, import the snippet into another file and call it as a
- component.
-
-
-### Default export
-
-1. Add content to your snippet file that you want to re-use across multiple
- locations. Optionally, you can add variables that can be filled in via props
- when you import the snippet.
-
-```mdx snippets/my-snippet.mdx
-Hello world! This is my content I want to reuse across pages. My keyword of the
-day is {word}.
-```
-
-
- The content that you want to reuse must be inside the `snippets` directory in
- order for the import to work.
-
-
-2. Import the snippet into your destination file.
-
-```mdx destination-file.mdx
----
-title: My title
-description: My Description
----
-
-import MySnippet from '/snippets/path/to/my-snippet.mdx';
-
-## Header
-
-Lorem impsum dolor sit amet.
-
-
-```
-
-### Reusable variables
-
-1. Export a variable from your snippet file:
-
-```mdx snippets/path/to/custom-variables.mdx
-export const myName = 'my name';
-
-export const myObject = { fruit: 'strawberries' };
-```
-
-2. Import the snippet from your destination file and use the variable:
-
-```mdx destination-file.mdx
----
-title: My title
-description: My Description
----
-
-import { myName, myObject } from '/snippets/path/to/custom-variables.mdx';
-
-Hello, my name is {myName} and I like {myObject.fruit}.
-```
-
-### Reusable components
-
-1. Inside your snippet file, create a component that takes in props by exporting
- your component in the form of an arrow function.
-
-```mdx snippets/custom-component.mdx
-export const MyComponent = ({ title }) => (
-
-
{title}
-
... snippet content ...
-
-);
-```
-
-
- MDX does not compile inside the body of an arrow function. Stick to HTML
- syntax when you can or use a default export if you need to use MDX.
-
-
-2. Import the snippet into your destination file and pass in the props
-
-```mdx destination-file.mdx
----
-title: My title
-description: My Description
----
-
-import { MyComponent } from '/snippets/custom-component.mdx';
-
-Lorem ipsum dolor sit amet.
-
-
-```
diff --git a/essentials/settings.mdx b/essentials/settings.mdx
deleted file mode 100644
index 884de13..0000000
--- a/essentials/settings.mdx
+++ /dev/null
@@ -1,318 +0,0 @@
----
-title: 'Global Settings'
-description: 'Mintlify gives you complete control over the look and feel of your documentation using the docs.json file'
-icon: 'gear'
----
-
-Every Mintlify site needs a `docs.json` file with the core configuration settings. Learn more about the [properties](#properties) below.
-
-## Properties
-
-
-Name of your project. Used for the global title.
-
-Example: `mintlify`
-
-
-
-
- An array of groups with all the pages within that group
-
-
- The name of the group.
-
- Example: `Settings`
-
-
-
- The relative paths to the markdown files that will serve as pages.
-
- Example: `["customization", "page"]`
-
-
-
-
-
-
-
- Path to logo image or object with path to "light" and "dark" mode logo images
-
-
- Path to the logo in light mode
-
-
- Path to the logo in dark mode
-
-
- Where clicking on the logo links you to
-
-
-
-
-
- Path to the favicon image
-
-
-
- Hex color codes for your global theme
-
-
- The primary color. Used for most often for highlighted content, section
- headers, accents, in light mode
-
-
- The primary color for dark mode. Used for most often for highlighted
- content, section headers, accents, in dark mode
-
-
- The primary color for important buttons
-
-
- The color of the background in both light and dark mode
-
-
- The hex color code of the background in light mode
-
-
- The hex color code of the background in dark mode
-
-
-
-
-
-
-
- Array of `name`s and `url`s of links you want to include in the topbar
-
-
- The name of the button.
-
- Example: `Contact us`
-
-
- The url once you click on the button. Example: `https://mintlify.com/docs`
-
-
-
-
-
-
-
-
- Link shows a button. GitHub shows the repo information at the url provided including the number of GitHub stars.
-
-
- If `link`: What the button links to.
-
- If `github`: Link to the repository to load GitHub information from.
-
-
- Text inside the button. Only required if `type` is a `link`.
-
-
-
-
-
-
- Array of version names. Only use this if you want to show different versions
- of docs with a dropdown in the navigation bar.
-
-
-
- An array of the anchors, includes the `icon`, `color`, and `url`.
-
-
- The [Font Awesome](https://fontawesome.com/search?q=heart) icon used to feature the anchor.
-
- Example: `comments`
-
-
- The name of the anchor label.
-
- Example: `Community`
-
-
- The start of the URL that marks what pages go in the anchor. Generally, this is the name of the folder you put your pages in.
-
-
- The hex color of the anchor icon background. Can also be a gradient if you pass an object with the properties `from` and `to` that are each a hex color.
-
-
- Used if you want to hide an anchor until the correct docs version is selected.
-
-
- Pass `true` if you want to hide the anchor until you directly link someone to docs inside it.
-
-
- One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin"
-
-
-
-
-
-
- Override the default configurations for the top-most anchor.
-
-
- The name of the top-most anchor
-
-
- Font Awesome icon.
-
-
- One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin"
-
-
-
-
-
- An array of navigational tabs.
-
-
- The name of the tab label.
-
-
- The start of the URL that marks what pages go in the tab. Generally, this
- is the name of the folder you put your pages in.
-
-
-
-
-
- Configuration for API settings. Learn more about API pages at [API Components](/api-playground/demo).
-
-
- The base url for all API endpoints. If `baseUrl` is an array, it will enable for multiple base url
- options that the user can toggle.
-
-
-
-
-
- The authentication strategy used for all API endpoints.
-
-
- The name of the authentication parameter used in the API playground.
-
- If method is `basic`, the format should be `[usernameName]:[passwordName]`
-
-
- The default value that's designed to be a prefix for the authentication input field.
-
- E.g. If an `inputPrefix` of `AuthKey` would inherit the default input result of the authentication field as `AuthKey`.
-
-
-
-
-
- Configurations for the API playground
-
-
-
- Whether the playground is showing, hidden, or only displaying the endpoint with no added user interactivity `simple`
-
- Learn more at the [playground guides](/api-playground/demo)
-
-
-
-
-
- Enabling this flag ensures that key ordering in OpenAPI pages matches the key ordering defined in the OpenAPI file.
-
- This behavior will soon be enabled by default, at which point this field will be deprecated.
-
-
-
-
-
-
- A string or an array of strings of URL(s) or relative path(s) pointing to your
- OpenAPI file.
-
- Examples:
-
- ```json Absolute
- "openapi": "https://example.com/openapi.json"
- ```
- ```json Relative
- "openapi": "/openapi.json"
- ```
- ```json Multiple
- "openapi": ["https://example.com/openapi1.json", "/openapi2.json", "/openapi3.json"]
- ```
-
-
-
-
-
- An object of social media accounts where the key:property pair represents the social media platform and the account url.
-
- Example:
- ```json
- {
- "x": "https://x.com/mintlify",
- "website": "https://mintlify.com"
- }
- ```
-
-
- One of the following values `website`, `facebook`, `x`, `discord`, `slack`, `github`, `linkedin`, `instagram`, `hacker-news`
-
- Example: `x`
-
-
- The URL to the social platform.
-
- Example: `https://x.com/mintlify`
-
-
-
-
-
- Configurations to enable feedback buttons
-
-
-
- Enables a button to allow users to suggest edits via pull requests
-
-
- Enables a button to allow users to raise an issue about the documentation
-
-
-
-
-
- Customize the dark mode toggle.
-
-
- Set if you always want to show light or dark mode for new users. When not
- set, we default to the same mode as the user's operating system.
-
-
- Set to true to hide the dark/light mode toggle. You can combine `isHidden` with `default` to force your docs to only use light or dark mode. For example:
-
-
- ```json Only Dark Mode
- "modeToggle": {
- "default": "dark",
- "isHidden": true
- }
- ```
-
- ```json Only Light Mode
- "modeToggle": {
- "default": "light",
- "isHidden": true
- }
- ```
-
-
-
-
-
-
-
-
- A background image to be displayed behind every page. See example with
- [Infisical](https://infisical.com/docs) and [FRPC](https://frpc.io).
-
diff --git a/favicon.svg b/favicon.svg
index b785c73..34b556a 100644
--- a/favicon.svg
+++ b/favicon.svg
@@ -1,19 +1,3 @@
-
+
\ No newline at end of file
diff --git a/images/api-getting-started/create-api-key.png b/images/api-getting-started/create-api-key.png
new file mode 100644
index 0000000..f713ab4
Binary files /dev/null and b/images/api-getting-started/create-api-key.png differ
diff --git a/images/concepts/monitoring/logs-tab.png b/images/concepts/monitoring/logs-tab.png
new file mode 100644
index 0000000..7a4f612
Binary files /dev/null and b/images/concepts/monitoring/logs-tab.png differ
diff --git a/images/concepts/monitoring/session-detail.png b/images/concepts/monitoring/session-detail.png
new file mode 100644
index 0000000..614b183
Binary files /dev/null and b/images/concepts/monitoring/session-detail.png differ
diff --git a/images/concepts/monitoring/tool-call-details.png b/images/concepts/monitoring/tool-call-details.png
new file mode 100644
index 0000000..aa83d01
Binary files /dev/null and b/images/concepts/monitoring/tool-call-details.png differ
diff --git a/images/concepts/projects-organizations/step-2.png b/images/concepts/projects-organizations/step-2.png
new file mode 100644
index 0000000..a03ba4c
Binary files /dev/null and b/images/concepts/projects-organizations/step-2.png differ
diff --git a/images/custom-servers/create-managed-server.png b/images/custom-servers/create-managed-server.png
new file mode 100644
index 0000000..e1f8df1
Binary files /dev/null and b/images/custom-servers/create-managed-server.png differ
diff --git a/images/custom-servers/env-vars-settings.png b/images/custom-servers/env-vars-settings.png
new file mode 100644
index 0000000..4eac5eb
Binary files /dev/null and b/images/custom-servers/env-vars-settings.png differ
diff --git a/images/custom-servers/external-server-registration.png b/images/custom-servers/external-server-registration.png
new file mode 100644
index 0000000..a64ec70
Binary files /dev/null and b/images/custom-servers/external-server-registration.png differ
diff --git a/images/custom-servers/navigate-managed-servers.png b/images/custom-servers/navigate-managed-servers.png
new file mode 100644
index 0000000..fa8f20e
Binary files /dev/null and b/images/custom-servers/navigate-managed-servers.png differ
diff --git a/images/integrations/browsing-catalog/integration-details.png b/images/integrations/browsing-catalog/integration-details.png
new file mode 100644
index 0000000..addb962
Binary files /dev/null and b/images/integrations/browsing-catalog/integration-details.png differ
diff --git a/images/integrations/browsing-catalog/servers-catalog.png b/images/integrations/browsing-catalog/servers-catalog.png
new file mode 100644
index 0000000..b13bea1
Binary files /dev/null and b/images/integrations/browsing-catalog/servers-catalog.png differ
diff --git a/images/metorial-101/deploying-mcp-servers/step-1.png b/images/metorial-101/deploying-mcp-servers/step-1.png
new file mode 100644
index 0000000..273062f
Binary files /dev/null and b/images/metorial-101/deploying-mcp-servers/step-1.png differ
diff --git a/images/metorial-101/deploying-mcp-servers/step-2.png b/images/metorial-101/deploying-mcp-servers/step-2.png
new file mode 100644
index 0000000..8f2ea0a
Binary files /dev/null and b/images/metorial-101/deploying-mcp-servers/step-2.png differ
diff --git a/images/metorial-101/deploying-mcp-servers/step-3.png b/images/metorial-101/deploying-mcp-servers/step-3.png
new file mode 100644
index 0000000..59754a9
Binary files /dev/null and b/images/metorial-101/deploying-mcp-servers/step-3.png differ
diff --git a/images/metorial-101/deploying-mcp-servers/step-4.png b/images/metorial-101/deploying-mcp-servers/step-4.png
new file mode 100644
index 0000000..a20ee3e
Binary files /dev/null and b/images/metorial-101/deploying-mcp-servers/step-4.png differ
diff --git a/images/metorial-101/monitoring-mcp-servers/errors.png b/images/metorial-101/monitoring-mcp-servers/errors.png
new file mode 100644
index 0000000..ffc67a0
Binary files /dev/null and b/images/metorial-101/monitoring-mcp-servers/errors.png differ
diff --git a/images/metorial-101/monitoring-mcp-servers/run-detail.png b/images/metorial-101/monitoring-mcp-servers/run-detail.png
new file mode 100644
index 0000000..8671d3b
Binary files /dev/null and b/images/metorial-101/monitoring-mcp-servers/run-detail.png differ
diff --git a/images/metorial-101/monitoring-mcp-servers/runs.png b/images/metorial-101/monitoring-mcp-servers/runs.png
new file mode 100644
index 0000000..9d60a3f
Binary files /dev/null and b/images/metorial-101/monitoring-mcp-servers/runs.png differ
diff --git a/images/metorial-101/monitoring-mcp-servers/session-detail.png b/images/metorial-101/monitoring-mcp-servers/session-detail.png
new file mode 100644
index 0000000..f095a98
Binary files /dev/null and b/images/metorial-101/monitoring-mcp-servers/session-detail.png differ
diff --git a/images/metorial-101/monitoring-mcp-servers/sessions.png b/images/metorial-101/monitoring-mcp-servers/sessions.png
new file mode 100644
index 0000000..97f3776
Binary files /dev/null and b/images/metorial-101/monitoring-mcp-servers/sessions.png differ
diff --git a/images/metorial-101/testing-mcp-servers/step-1.png b/images/metorial-101/testing-mcp-servers/step-1.png
new file mode 100644
index 0000000..a20ee3e
Binary files /dev/null and b/images/metorial-101/testing-mcp-servers/step-1.png differ
diff --git a/images/metorial-101/testing-mcp-servers/step-2.png b/images/metorial-101/testing-mcp-servers/step-2.png
new file mode 100644
index 0000000..804faba
Binary files /dev/null and b/images/metorial-101/testing-mcp-servers/step-2.png differ
diff --git a/images/metorial-101/testing-mcp-servers/step-3.png b/images/metorial-101/testing-mcp-servers/step-3.png
new file mode 100644
index 0000000..9ddbaa1
Binary files /dev/null and b/images/metorial-101/testing-mcp-servers/step-3.png differ
diff --git a/images/metorial-101/testing-mcp-servers/step-4.png b/images/metorial-101/testing-mcp-servers/step-4.png
new file mode 100644
index 0000000..12fcf2e
Binary files /dev/null and b/images/metorial-101/testing-mcp-servers/step-4.png differ
diff --git a/images/metorial-101/testing-mcp-servers/step-5.png b/images/metorial-101/testing-mcp-servers/step-5.png
new file mode 100644
index 0000000..0f2a124
Binary files /dev/null and b/images/metorial-101/testing-mcp-servers/step-5.png differ
diff --git a/index.mdx b/index.mdx
index 15c23fb..095c7bd 100644
--- a/index.mdx
+++ b/index.mdx
@@ -1,97 +1,47 @@
---
-title: "Introduction"
-description: "Welcome to the new home for your documentation"
+title: "Welcome to Metorial"
+description: "Documentation for deploying and managing MCP servers with Metorial"
---
-## Setting up
+This documentation provides an overview of the Metorial API and SDKs, including guides, references, and examples to help you get started.
-Get your documentation site up and running in minutes.
+## Getting Started
-
- Follow our three step quickstart guide.
-
+Learn more about how to get set up with Metorial.
-## Make it yours
-
-Design a docs site that looks great and empowers your users.
-
-
-
- Edit your docs locally and preview them in real time.
+
+
+ Get started with Metorial in minutes.
+
+
+ Learn how to deploy a MCP server in your Metorial project.
-
- Customize the design and colors of your site to match your brand.
+
+ Learn how to test your servers in the Metorial dashboard.
-
- Organize your docs to help users find what they need and succeed with your product.
+
+ Learn how to use your deployed MCP servers.
-
- Auto-generate API documentation from OpenAPI specifications.
+
+ Learn how to monitor your MCP servers.
-
+
-## Create beautiful pages
+## For Developers
-Everything you need to create world-class documentation.
+Explore the Metorial API and SDKs to build powerful applications and integrations with Metorial.
-
-
- Use MDX to style your docs pages.
+
+
+ Learn how to use the Metorial API.
-
- Add sample code to demonstrate how to use your product.
+
+ Integrate Metorial with your applications using our client libraries.
-
- Display images and other media.
+
+ Integrate Metorial with your applications using our client libraries.
-
- Write once and reuse across your docs.
+
+ Create and manage API keys for your Metorial project.
-
-
-## Need inspiration?
-
-
- Browse our showcase of exceptional documentation sites.
-
+
diff --git a/integrations-api-key.mdx b/integrations-api-key.mdx
new file mode 100644
index 0000000..2cae397
--- /dev/null
+++ b/integrations-api-key.mdx
@@ -0,0 +1,111 @@
+---
+title: 'Setting Up API Key Integrations'
+description: 'Deploy and configure API key-based integrations in Metorial'
+---
+
+API key integrations use a single set of credentials for your entire application. Perfect for services like search APIs (Exa, Tavily) where you don't need user-specific authorization—just get an API key, deploy, and start building.
+
+
+**What you'll learn:**
+- How to deploy API key-based integrations
+- How to configure and test integrations
+
+**Related resources:**
+- [Deploy Your First Server](metorial-101-deploying)
+- [Integrations Overview](integrations-overview)
+
+
+## Deploying an API Key Integration
+
+
+
+ Sign up for the service (e.g., Exa, Tavily) and generate an API key.
+
+
+ In Metorial, go to **Servers** and search for the integration.
+
+
+ Click **Deploy**, name your deployment, and paste your API key.
+
+
+ Use the test console to verify the deployment works.
+
+
+
+## Using API Key Integrations
+
+After deploying your integration, pass the deployment ID to your Metorial session. The integration handles authentication automatically using the API key you configured.
+
+
+```typescript TypeScript
+import { Metorial } from 'metorial';
+import { metorialAiSdk } from '@metorial/ai-sdk';
+import { anthropic } from '@ai-sdk/anthropic';
+import { streamText } from 'ai';
+
+let metorial = new Metorial({
+ apiKey: process.env.METORIAL_API_KEY
+});
+
+await metorial.withProviderSession(
+ metorialAiSdk,
+ {
+ serverDeployments: [
+ { serverDeploymentId: 'your-exa-deployment-id' }
+ ],
+ streaming: true
+ },
+ async ({ tools, closeSession }) => {
+ let result = streamText({
+ model: anthropic('claude-sonnet-4-5'),
+ prompt: 'Search for AI news',
+ tools: tools,
+ onFinish: async () => await closeSession()
+ });
+
+ for await (let text of result.textStream) {
+ process.stdout.write(text);
+ }
+ }
+);
+```
+
+```python Python
+import asyncio
+import os
+from metorial import Metorial, MetorialAnthropic
+from anthropic import AsyncAnthropic
+
+async def main():
+ metorial = Metorial(api_key=os.getenv("METORIAL_API_KEY"))
+ anthropic = AsyncAnthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
+
+ async def session_handler(session):
+ response = await anthropic.messages.create(
+ model="claude-sonnet-4-20250514",
+ max_tokens=1024,
+ messages=[{"role": "user", "content": "Search for AI news"}],
+ tools=session["tools"]
+ )
+ print(response.content)
+
+ await metorial.with_provider_session(
+ MetorialAnthropic,
+ [{"serverDeploymentId": "your-exa-deployment-id"}],
+ session_handler
+ )
+
+asyncio.run(main())
+```
+
+
+## What's Next?
+
+
+
+ Set up user-authorized integrations.
+
+
+ Build your first AI agent.
+
+
diff --git a/integrations-browsing-catalog.mdx b/integrations-browsing-catalog.mdx
new file mode 100644
index 0000000..2e1d33b
--- /dev/null
+++ b/integrations-browsing-catalog.mdx
@@ -0,0 +1,54 @@
+---
+title: 'Browsing the Server Catalog'
+description: 'Find and deploy integrations from the Metorial server catalog'
+---
+
+
+**What you'll learn:**
+- How to navigate the server catalog
+- How to search for integrations
+
+**Related resources:**
+- [Deploy Your First Server](/metorial-101-deploying)
+
+
+## Accessing the Catalog
+
+
+
+ Visit [app.metorial.com](https://app.metorial.com) and select your project.
+
+
+ Click **Servers** in the navigation menu to browse available integrations.
+
+ 
+
+
+
+
+## Finding Integrations
+
+Use the search box to find specific integrations by name.
+
+Browse by category to explore related integrations.
+
+
+## Integration Details
+
+Click on an integration to see:
+- Description of what it does
+- Available tools
+- Configuration requirements
+
+
+
+## What's Next?
+
+
+
+ Set up an integration that uses API keys.
+
+
+ Set up an integration that requires user authorization.
+
+
diff --git a/integrations-enterprise-byo.mdx b/integrations-enterprise-byo.mdx
new file mode 100644
index 0000000..7d31ec7
--- /dev/null
+++ b/integrations-enterprise-byo.mdx
@@ -0,0 +1,107 @@
+---
+title: 'Enterprise BYO'
+description: 'Bring Your Own credentials for enterprise deployments with dynamic server deployments'
+---
+
+
+**What you'll learn:**
+- Dynamic server deployment creation via API
+- BYO OAuth app configuration
+- Enterprise compliance patterns
+
+**Related resources:**
+- [Getting Started with the API](/api-getting-started)
+- [OAuth Integrations](/integrations-oauth)
+
+
+Need full control over OAuth apps and API keys for compliance, branding, or security? Metorial lets you create server deployments dynamically via the API using your own credentials—no dashboard required.
+
+## Why BYO?
+
+Using your own credentials gives you full control over how your users authenticate and how your infrastructure handles sensitive data. Enterprise teams choose BYO for three main reasons:
+
+
+**Compliance & Security:**
+- Keep credentials in your own infrastructure
+- Meet data residency requirements
+- Audit and rotate credentials on your schedule
+
+
+
+**Branding & Control:**
+- OAuth consent screens show your company name
+- Use your company's existing OAuth apps
+- Control which permissions are requested
+
+
+
+**Multi-tenancy:**
+- Create isolated deployments per customer
+- Different credentials for different organizations
+- Scale deployment creation programmatically
+
+
+## Dynamic Server Deployments
+
+Create server deployments programmatically via the Metorial API instead of using the dashboard.
+
+**The flow:**
+1. Call the API with your credentials to create a deployment
+2. Receive a deployment ID
+3. Use the deployment ID in your SDK like any other integration
+
+Ideal for multi-tenant applications where each customer needs isolated credentials, or enterprises managing multiple OAuth apps across teams.
+
+See the [Metorial API documentation](/api-getting-started) for endpoint details, authentication, and request/response schemas.
+
+## BYO OAuth Apps
+
+Use your own OAuth app credentials instead of Metorial's default OAuth apps.
+
+**Setup process:**
+
+
+
+ Register your OAuth app with the service (GitHub, Slack, Google, etc.). Save your client ID and client secret.
+
+
+
+ Call the Metorial API to create a server deployment, passing your OAuth app credentials in the request body.
+
+
+
+ Use the returned deployment ID in your SDK code like any other deployment. Users will see your OAuth app name when authorizing.
+
+
+
+
+**Benefits:**
+- Consent screens show your company name and branding
+- Full control over scopes and permissions
+- Integrate with existing identity systems
+- Credentials stay in your infrastructure
+
+
+## BYO API Keys
+
+Use your own API keys for integrations like Exa, Brave, or Tavily.
+
+
+**Use cases:**
+- Isolate usage per customer or team
+- Track costs per deployment
+- Rotate keys without affecting other deployments
+
+
+Create deployments via the API with your keys—Metorial uses them when tools are called.
+
+## What's Next?
+
+
+
+ Learn how to use the Metorial API.
+
+
+ Learn about OAuth integration patterns.
+
+
diff --git a/integrations-oauth.mdx b/integrations-oauth.mdx
new file mode 100644
index 0000000..fa35427
--- /dev/null
+++ b/integrations-oauth.mdx
@@ -0,0 +1,177 @@
+---
+title: 'Setting Up OAuth Integrations'
+description: 'Deploy and configure OAuth-based integrations that require user authorization'
+---
+
+OAuth integrations let users authorize access to their personal accounts—like Slack workspaces, GitHub repos, or Google Calendars—so your AI can perform actions on their behalf.
+
+
+**What you'll learn:**
+- Setting up OAuth for your users
+- Managing OAuth sessions
+- Advanced patterns (BYO OAuth, export/import)
+
+**Related resources:**
+- [SDK OAuth Guide](sdk-oauth)
+- [Enterprise BYO](/integrations-enterprise-byo)
+
+
+## Basic OAuth Setup
+
+Each user authorizes once, you store their OAuth session ID in your database, then reuse it for future requests.
+
+**The flow:**
+1. User clicks "Connect Slack" (or GitHub, Google, etc.) in your app
+2. They authorize access via the OAuth screen
+3. You receive an `oauthSessionId` and store it for that user
+4. Pass that session ID whenever creating MCP sessions for that user
+
+
+```typescript TypeScript
+// Create OAuth session (once per user)
+let oauthSession = await metorial.oauth.sessions.create({
+ serverDeploymentId: 'your-slack-deployment-id'
+});
+
+// Show user the authorization URL
+console.log('Authorize here:', oauthSession.url);
+
+// Wait for completion
+await metorial.oauth.waitForCompletion([oauthSession]);
+
+// Store oauthSession.id for this user in your database
+await db.users.update(userId, { slackOAuthSessionId: oauthSession.id });
+```
+
+```python Python
+# Create OAuth session (once per user)
+oauth_session = metorial.oauth.sessions.create(
+ server_deployment_id="your-slack-deployment-id"
+)
+
+# Show user the authorization URL
+print(f"Authorize here: {oauth_session.url}")
+
+# Wait for completion
+await metorial.oauth.wait_for_completion([oauth_session])
+
+# Store oauth_session.id for this user in your database
+await db.users.update(user_id, slack_oauth_session_id=oauth_session.id)
+```
+
+
+## Using OAuth Sessions
+
+After a user authorizes, retrieve their stored OAuth session ID from your database and pass it when creating MCP sessions. This connects the session to their authorized account, giving your AI access to their data.
+
+
+```typescript TypeScript
+await metorial.withProviderSession(
+ provider,
+ {
+ serverDeployments: [
+ {
+ serverDeploymentId: 'slack-deployment-id',
+ oauthSessionId: storedOAuthSessionId // From your database
+ }
+ ]
+ },
+ async ({ tools, closeSession }) => {
+ // Tools now have access to user's Slack
+ await closeSession();
+ }
+);
+```
+
+```python Python
+async def session_handler(session):
+ # Tools now have access to user's Slack
+ # Use session["tools"] and session["callTools"]
+ pass
+
+await metorial.with_provider_session(
+ MetorialAnthropic,
+ [
+ {
+ "serverDeploymentId": "slack-deployment-id",
+ "oauthSessionId": stored_oauth_session_id # From your database
+ }
+ ],
+ session_handler
+)
+```
+
+
+## Advanced Features
+
+### Enterprise BYO (Bring Your Own) OAuth
+
+Need to use your own OAuth apps instead of Metorial's? Create server deployments via the API with your own credentials.
+
+
+**Why use BYO OAuth:**
+- OAuth consent screens show your company name
+- Use existing OAuth apps from your organization
+- Meet enterprise security and compliance requirements
+- Full control over OAuth scopes and permissions
+
+
+**How it works:** Call the Server Deployment API with your OAuth app credentials (client ID, client secret) to create a custom deployment. Users authorize via your OAuth app, and you use the deployment like any other.
+
+See [Enterprise BYO](integrations-enterprise-byo) for detailed setup instructions.
+
+### OAuth Export/Import
+
+Manage OAuth tokens outside of Metorial or migrate from existing systems.
+
+**Exporting tokens:**
+
+Extract OAuth credentials from Metorial sessions for use in your own infrastructure, migration to another system, or backup purposes.
+
+
+```typescript TypeScript
+// Export OAuth session credentials
+let credentials = await metorial.oauth.sessions.export(oauthSessionId);
+```
+
+```python Python
+# Export OAuth session credentials
+credentials = await metorial.oauth.sessions.export(oauth_session_id)
+```
+
+
+**Importing tokens:**
+
+Import existing OAuth tokens into Metorial instead of asking users to re-authorize. Useful when migrating from another system or if users already have OAuth tokens from your app.
+
+
+```typescript TypeScript
+// Import existing OAuth credentials
+let oauthSession = await metorial.oauth.sessions.import({
+ serverDeploymentId: 'your-deployment-id',
+ credentials: existingOAuthCredentials
+});
+```
+
+```python Python
+# Import existing OAuth credentials
+oauth_session = await metorial.oauth.sessions.import_(
+ server_deployment_id="your-deployment-id",
+ credentials=existing_oauth_credentials
+)
+```
+
+
+## What's Next?
+
+
+
+ Detailed SDK documentation for OAuth.
+
+
+ Learn about the Metorial API.
+
+
+ Simpler integrations without OAuth.
+
+
diff --git a/integrations-overview.mdx b/integrations-overview.mdx
new file mode 100644
index 0000000..d83d471
--- /dev/null
+++ b/integrations-overview.mdx
@@ -0,0 +1,108 @@
+---
+title: 'Integrations Overview'
+description: 'Pre-built MCP server integrations that you can deploy without writing any code'
+---
+
+
+**What you'll learn:**
+- What integrations are available
+- Authentication types (OAuth vs API key)
+- Licensing and deployment options
+
+**Related resources:**
+- [Browsing the Catalog](integrations-browsing-catalog)
+- [Deploy Your First Server](metorial-101-deploying)
+
+
+## What Are Integrations?
+
+Integrations are pre-built MCP servers that provide ready-to-use tools for popular services. Instead of building API clients from scratch, you can deploy integrations for services like GitHub, Slack, Google Calendar, Exa, and more.
+
+Each integration exposes tools that your AI models can call directly. For example, the GitHub integration provides tools for creating issues, reviewing pull requests, and managing repositories—all without writing any integration code yourself.
+
+## Licensing
+
+Metorial uses the **FSL (Functional Source License)** - source-available with commercial licensing for production.
+
+**What this means for developers:**
+- **Free during development**: Build and test without restrictions
+- **Source available**: Audit the code for security and compliance
+- **Production requires a license**: Contact us when you're ready to deploy
+
+The cloud SaaS version at [app.metorial.com](https://app.metorial.com) includes licensing—just sign up and deploy.
+
+## Deployment Options
+
+### Cloud SaaS (Recommended)
+
+Start building immediately with Metorial's hosted cloud at [app.metorial.com](https://app.metorial.com). No infrastructure setup required—just create an account and deploy integrations.
+
+
+**Ideal for**: Teams who want to focus on building AI features rather than managing infrastructure.
+
+
+### Enterprise On-Premises
+
+Self-host Metorial in your own cloud environment when you need full control over data and infrastructure. Metorial runs on **HashiStack** (Nomad, Vault, Consul) and deploys to AWS, GCP, Azure, or your private cloud.
+
+
+**Ideal for**: Enterprises with strict data residency requirements or compliance needs.
+
+
+Contact us for enterprise licensing and deployment support.
+
+## Authentication Types
+
+Integrations use two authentication patterns depending on whether they access shared services or user-specific data.
+
+### API Key Integrations
+
+Best for services where one API key serves your entire application. The integration uses your credentials to make requests on behalf of your app.
+
+
+**Examples**: Exa (search), Tavily (search), Brave (search)
+
+**When to use**: Single-tenant applications, internal tools, or services that don't have user-specific data.
+
+**Setup**: Get an API key from the service, create a deployment in Metorial, and paste your key. Done.
+
+
+### OAuth Integrations
+
+Required when each user needs to authorize access to their own account. The integration acts on behalf of individual users with their explicit permission.
+
+
+**Examples**: Slack, GitHub, Google Calendar, Gmail
+
+**When to use**: Multi-tenant applications where users connect their personal accounts.
+
+**How it works**: Users authorize via OAuth, you store their session ID, and pass it when creating MCP sessions. Each user's data stays isolated.
+
+
+See [OAuth Integrations](integrations-oauth) for implementation patterns.
+
+## Choosing Integrations
+
+You can mix both authentication types in the same application. For example, use an API key integration for search (Exa) while using OAuth integrations for user-specific services (Slack, GitHub). When creating MCP sessions, pass multiple deployments together—Metorial combines all their tools into a single tool list for your AI model.
+
+
+**Single-user applications**: API key integrations work well.
+
+**Multi-user applications**: Use OAuth integrations for user-specific access.
+
+**Enterprise**: Consider BYO OAuth apps with dynamic server deployments.
+
+
+## Getting Started
+
+
+
+ Explore available integrations.
+
+
+ Deploy an API key-based integration.
+
+
+ Deploy an OAuth-based integration.
+
+
diff --git a/logo/dark.svg b/logo/dark.svg
index 8b343cd..a68186b 100644
--- a/logo/dark.svg
+++ b/logo/dark.svg
@@ -1,21 +1,13 @@
-
-
-
-
-
-
-
-#### Videos
-
-Use the HTML video element for self-hosted video content:
-
-
-
-Embed YouTube videos using iframe elements:
-
-
-
-#### Tooltips
-
-Example of tooltip usage:
-
-
-
-
-## Code formatting
-
-We suggest using extensions on your IDE to recognize and format MDX. If you're a VSCode user, consider the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting.
-
-## Troubleshooting
-
-
-
-## Image
-
-### Using Markdown
-
-The [markdown syntax](https://www.markdownguide.org/basic-syntax/#images) lets you add images using the following code
-
-```md
-
-```
-
-Note that the image file size must be less than 5MB. Otherwise, we recommend hosting on a service like [Cloudinary](https://cloudinary.com/) or [S3](https://aws.amazon.com/s3/). You can then use that URL and embed.
-
-### Using embeds
-
-To get more customizability with images, you can also use [embeds](/writing-content/embed) to add images
-
-```html
-
-```
-
-## Embeds and HTML elements
-
-
-
-