### 30-Second Getting Started with In-Process Server

Source: https://docs.qoder.com/en/cli/sdk/mcp

A quick start example for setting up an in-process MCP server. This method is recommended for its simplicity and direct access to host state.

```typescript
import { query, createSdkMcpServer, tool } from '@qoder-ai/qoder-agent-sdk'

// Define a tool with a Zod schema
const myTool = tool({
  name: 'myTool',
  description: 'A sample tool',
  inputSchema: z.object({
    name: z.string()
  }),
  outputSchema: z.object({
    greeting: z.string()
  }),
  handler: async ({ name }) => {
    return { greeting: `Hello, ${name}!` }
  }
})

// Register the in-process server with the tool
query.registerServer(
  createSdkMcpServer({
    tools: [myTool]
  })
)

// The Agent can now call myTool via query()
const result = await query({
  toolName: 'myTool',
  input: {
    name: 'World'
  }
})

console.log(result.greeting) // Output: Hello, World!
```

--------------------------------

### Example Skill: One-Click Installation

Source: https://docs.qoder.com/qoderwork/skills

This example shows a Skill step for one-click installation, where a recipient clicks a link to jump directly to QoderWork and complete installation.

```javascript
const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];
const {useMDXComponents: _provideComponents} = arguments[0];
function _createMdxContent(props) {
 const _components = {
 blockquote: "blockquote",
 code: "code",
 li: "li",
 ol: "ol",
 p: "p",
 strong: "strong",
 ..._provideComponents(),
 ...props.components
 }, {Frame, Heading, OptimizedImage, Step, Steps} = _components;
 if (!Frame) _missingMdxReference("Frame", true);
 if (!Heading) _missingMdxReference("Heading", true);
 if (!OptimizedImage) _missingMdxReference("OptimizedImage", true);
 if (!Step) _missingMdxReference("Step", true);
 if (!Steps) _missingMdxReference("Steps", true);
 return _jsxs(_Fragment, {
 children: [_jsx(Heading, {
 level: "2",
 id: "what-are-skills%3F",
 children: "What Are Skills?"
 }), "\n", _jsx(_components.p, {
 children: "We all have tasks we do over and over — writing weekly reports, organizing docs, generating infographics. Explaining your requirements, preferences, and workflow to AI from scratch every time is tedious and error-prone."
 }), "\n", _jsx(_components.p, {
 children: "That’s what Skills are for. A Skill is a pre-written playbook that tells QoderWork how to handle a specific type of task: what steps to follow, what format to use, and what details to watch out for. Define it once, and QoderWork will automatically recognize and apply it in future conversations — like a well-trained assistant that delivers consistent, reliable results every time."
 }), "\n", _jsxs(_components.p, {
 children: ["Under the hood, each Skill is simply a folder containing a ", _jsx(_components.code, {
 children: "SKILL.md"
 }), " file, stored in ", _jsx(_components.code, {
 children: "~/.qoderwork/skills/"
 }), ". The ", _jsx(_components.code, {
 children: "SKILL.md"
 }), " describes the skill’s name, trigger conditions, and execution steps in plain language — no code required, just write down your process and expertise."]
 }), "\n", _jsx(Heading, {
 level: "2",
 id: "why-use-skills%3F",
 children: "Why Use Skills?"
 }), "\n", _jsx(_components.p, {
 children: _jsx(_components.strong, {
 children: "Stop repeating yourself"
 })
 }), "\n", _jsx(_components.p, {
 children: "Every new conversation means re-explaining what you need and how you like it done. With a Skill, all of that is captured once — just trigger it with a single message, or let QoderWork pick it up automatically. No more wasting time on the same instructions."
 }), "\n", _jsx(_components.p, {
 children: _jsx(_components.strong, {
 children: "Consistent output, every time"
 })
 }), "\n", _jsx(_components.p, {
 children: "When your team has specific formatting or style requirements (say, a weekly report that must include certain sections), a Skill ensures every output meets the standard — regardless of who’s using it or how the conversation goes."
 }), "\n", _jsx(_components.p, {
 children: _jsx(_components.strong, {
 children: "Turn personal know-how into a reusable asset"
 })
 }), "\n", _jsx(_components.p, {
 children: "The best practices, tricks, and judgment calls you’ve built up over time can all be captured in a Skill. Share it with teammates and let your expertise flow across the organization, instead of staying locked in your head."
 }), "\n", _jsx(_components.p, {
 children: _jsx(_components.strong, {
 children: "Turn a generalist into a specialist"
 })
 }), "\n", _jsx(_components.p, {
 children: "QoderWork already has broad general capabilities."
 }) 
])
}

```

--------------------------------

### In-Process Server: 30-Second Getting Started

Source: https://docs.qoder.com/llms-full.txt

Defines a simple 'greet' tool and registers it with an in-process MCP server. This example demonstrates how to create a server instance and use it within the `query()` function.

```python
import asyncio
from typing import Annotated

from qoder_agent_sdk import (
    QoderAgentOptions,
    create_sdk_mcp_server,
    query,
    tool,
)


@tool("greet", "Greet someone.", {"name": Annotated[str, "Recipient name"]})
async def greet(args):
    return {"content": [{"type": "text", "text": f"Hello, {args['name']}!"}]}


server = create_sdk_mcp_server(name="my_tools", tools=[greet])


async def main():
    options = QoderAgentOptions(
        mcp_servers={"my_tools": server},
        allowed_tools=["mcp__my_tools__greet"],
    )
    async for msg in query(prompt="Use the greet tool to greet Alice", options=options):
        print(msg)


asyncio.run(main())
```

--------------------------------

### 30-Second Getting Started with In-Process Server

Source: https://docs.qoder.com/en/cli/sdk/mcp

Quickly set up an in-process tool by defining an async function with a Zod schema. This example demonstrates the basic import and setup for an in-process server using the Qoder Agent SDK.

```typescript
import { query, createSdkMcpServer, tool } from '@qoder-ai/qoder-agent-sdk'

```

--------------------------------

### Install System Packages with Apt

Source: https://docs.qoder.com/llms-full.txt

Use the 'packages.apt' field to specify system dependencies to be installed at container startup. This example installs PostgreSQL client, Redis tools, and FFmpeg.

```json
{
  "config": {
    "packages": {
      "apt": ["postgresql-client", "redis-tools", "ffmpeg"]
    }
  }
}
```

--------------------------------

### APT Package Installation Example

Source: https://docs.qoder.com/cloud-agents/api/environments/schemas

Specifies Debian/Ubuntu system packages to be installed using 'apt-get install -y'. Example includes git, curl, and build-essential.

```javascript
apt
```

```javascript
array of string
```

```javascript
apt-get install -y
```

```javascript
[\"git\", \"curl\", \"build-essential\"]
```

--------------------------------

### Multi-tool Example Setup

Source: https://docs.qoder.com/en/cli/sdk/mcp

Defines a 'search_docs' tool and creates an MCP server instance with multiple tools.

```typescript
const searchDocs = tool(
  'search_docs',
  'Search internal docs and return relevant snippets.',
  {
    query: z.string().describe('Search keywords'),
    maxResults: z.number().int().min(1).max(20).optional()
      .describe('Maximum number of results, defaults to 5'),
  },
  async ({ query, maxResults = 5 }) => {
    const hits = await docs.search(query, maxResults);
    return { content: [{ type: 'text', text: JSON.stringify(hits) }] };
  },
  { annotations: { readOnlyHint: true } },
);

const server = createSdkMcpServer({
  name: 'kb',
  tools: [searchDocs, queryDb /* ... */],
});

```

--------------------------------

### Example Wiki Plan Configuration

Source: https://docs.qoder.com/llms-full.txt

An example of a wiki_plan.yaml file demonstrating how to guide documentation generation with specific notes and document targets.

```yaml
version: 1

repowiki:
  notes:
    - text: "Documentation should focus on business workflows rather than code details, targeting new engineers"
  documents:
    - title: "System Architecture Overview"
      goal: "Describe overall system architecture, core modules and their interactions"
    - title: "Order System"
      goal: "Explain the full order lifecycle"
      parent: "System Architecture Overview"

knowledgecard:
  notes:
    - text: "Focus on modeling the payment and order core subsystems"

scope:
  include:
    - "src/**"
  exclude:
    - "**/test/**"
```

--------------------------------

### Complete MCP SDK Example

Source: https://docs.qoder.com/en/cli/sdk/mcp

This example demonstrates the complete setup and usage of the MCP SDK, including necessary imports and tool definitions. Ensure you have the 'qoder-agent-sdk' and 'zod' libraries installed.

```typescript
import { query, createSdkMcpServer, tool } from '@qoder-ai/qoder-agent-sdk';
import { z } from 'zod';

// 1. Define application tools
```

--------------------------------

### Python SDK Quick Start Example

Source: https://docs.qoder.com/en/cli/sdk/python/quick-start

This example shows how to initialize the Qoder Agent SDK, configure options like allowed tools and permission mode, send a prompt for code analysis and test generation, and process the streaming response, distinguishing between text and tool use messages.

```python
import anyio

from qoder_agent_sdk import (
    AssistantMessage,
    QoderAgentOptions,
    ResultMessage,
    TextBlock,
    ToolUseBlock,
    access_token_from_env,
    query,
)


async def main():
    options = QoderAgentOptions(
        auth=access_token_from_env(),
        allowed_tools=["Read", "Write", "Edit", "Glob", "Grep", "Bash"],
        permission_mode="acceptEdits",  # Auto-approve file edits
    )

    async for message in query(
        prompt=(
            "Analyze the codebase, find functions without test coverage, "
            "and write unit tests for them."
        ),
        options=options,
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(block.text)              # AI text response
                elif isinstance(block, ToolUseBlock):
                    print(f"Tool: {block.name}")   # Tool being called
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")      # Final result


anyio.run(main)

```

--------------------------------

### Install Extra Software with apt

Source: https://docs.qoder.com/cloud-agents/container-reference

Use the Environment's 'packages' field to install additional dependencies via apt. This example installs postgresql-client, redis-tools, and ffmpeg.

```json
{
 "config": {
 "packages": {
 "apt": [
 "postgresql-client",
 "redis-tools",
 "ffmpeg"
 ]
 }
 }
}
```

--------------------------------

### NPM Package Installation Example

Source: https://docs.qoder.com/cloud-agents/api/environments/schemas

Specifies Node.js packages to be installed globally using 'npm install -g'. Example includes typescript and eslint.

```javascript
npm
```

```javascript
array of string
```

```javascript
npm install -g
```

```javascript
[\"typescript@5.0.0\", \"eslint\"]
```

--------------------------------

### Multi-tool Example Configuration

Source: https://docs.qoder.com/en/cli/sdk/mcp

Example demonstrating how to configure an MCP SDK server with multiple tools. This setup is suitable for complex SDK clients requiring diverse functionalities.

```typescript
import { mcp } from "@qoder/sdk";

mcp.query({
  servers: [
    {
      name: "my-server",
      version: "1.0.0",
      tools: [
        {
          name: "tool1",
          handler: async () => ({ data: "result1" }),
        },
        {
          name: "tool2",
          handler: async () => ({ data: "result2" }),
        },
      ],
    } as McpSdkServerConfigWithInstance,
  ],
});

```

--------------------------------

### Example Request - Get Session

Source: https://docs.qoder.com/cloud-agents/api/sessions/get

Demonstrates how to make a GET request to retrieve session details.

```bash
curl --request GET \
  --url 'https://api.qoder.com/cloud-agents/sessions/s-1234567890abcdef' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

--------------------------------

### End-to-End Quickstart Script

Source: https://docs.qoder.com/cloud-agents/quickstart

This shell script demonstrates the complete flow for interacting with Qoder Cloud Agents. It includes setup for authentication and API calls.

```shellscript
#!/bin/bash
# Qoder Cloud Agents quickstart script
# Usage: export QODER_PAT="your-token" && bash quickstart.sh

set -euo pipefail

BASE_URL="https://api.qoder.com/api/v1/cloud"
HEADERS=(
  -H "Authorization: Bearer $QODER_PAT"
)

echo
```

--------------------------------

### Qoder Cloud Agents Quickstart Script

Source: https://docs.qoder.com/cloud-agents/quickstart

This bash script automates the process of setting up and interacting with Qoder Cloud Agents. It handles environment creation, agent setup, session initiation, message sending, and event streaming. Ensure you have exported your QODER_PAT environment variable before running.

```bash
#!/bin/bash
# Qoder Cloud Agents quickstart script
# Usage: export QODER_PAT="your-token" && bash quickstart.sh

set -euo pipefail

BASE_URL="https://api.qoder.com/api/v1/cloud"
HEADERS=(
  -H "Authorization: Bearer $QODER_PAT"
)

echo "=== Step 1: Fetch environment ==="
ENV_ID=$(curl -s "$BASE_URL/environments" "${HEADERS[@]}" | jq -r '.data[0].id')
if [ "$ENV_ID" = "null" ] || [ -z "$ENV_ID" ]; then
  echo "No environment found. Creating a default one..."
  ENV_ID=$(curl -s -X POST "$BASE_URL/environments" \
    "${HEADERS[@]}" \
    -H "Content-Type: application/json" \
    -d '{"name":"default","config":{"type":"cloud","networking":{"type":"unrestricted"}}}' | jq -r '.id')
fi
echo "Environment ID: $ENV_ID"

echo "=== Step 2: Get or create the Agent ==="
AGENT_ID=$(curl -s "$BASE_URL/agents" "${HEADERS[@]}" | jq -r '.data[0].id')
if [ "$AGENT_ID" = "null" ] || [ -z "$AGENT_ID" ]; then
  AGENT_ID=$(curl -s -X POST "$BASE_URL/agents" \
    "${HEADERS[@]}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "quickstart-agent",
      "model": "ultimate",
      "system": "You are an efficient programming assistant.",
      "tools": [{"type": "agent_toolset_20260401", "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]}]
    }' | jq -r '.id')
fi
echo "Agent ID: $AGENT_ID"

echo "=== Step 3: Create the Session ==="
SESSION_ID=$(curl -s -X POST "$BASE_URL/sessions" \
  "${HEADERS[@]}" \
  -H "Content-Type: application/json" \
  -d "{\"agent\": \"$AGENT_ID\", \"environment_id\": \"$ENV_ID\"}" | jq -r '.id')
echo "Session ID: $SESSION_ID"

echo "=== Step 4: Send a message ==="
curl -s -X POST "$BASE_URL/sessions/$SESSION_ID/events" \
  "${HEADERS[@]}" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {"type": "user.message", "content": [{"type": "text", "text": "Print Hello World and tell me the current system time."}]}
    ]
  }' | jq .

echo "=== Step 5: Stream events ==="
echo "(Press Ctrl+C to exit)"
curl -s -N "$BASE_URL/sessions/$SESSION_ID/events/stream" "${HEADERS[@]}"

```

--------------------------------

### Configure Agent with Tools and Prompts

Source: https://docs.qoder.com/en/cli/sdk/agents

Example of configuring an agent with specific tools and a descriptive prompt. This setup is useful for defining agent capabilities and guiding its behavior.

```typescript
const q = {
 prompt: "Add input validation to the user registration endpoint.",
 options: {
 // Pre-authorize Agent tool calls. If options.tools restricts the tool set, include 'Agent' there too.
 allowedTools: ["Agent"],
 agents: {
 researcher: {
 description: "Reads existing code to understand patterns and constraints.",
 prompt: "Research relevant files and report implementation constraints. Do
```

--------------------------------

### Complete Custom Tool Integration Example

Source: https://docs.qoder.com/llms-full.txt

A minimal, runnable example demonstrating the three main steps: defining a tool with `@tool()`, registering it with `create_sdk_mcp_server`, and attaching it to `QoderAgentOptions`.

```python
import asyncio
import json

from mcp.types import ToolAnnotations

from qoder_agent_sdk import (
    QoderAgentOptions,
    create_sdk_mcp_server,
    qodercli_auth,
    query,
    tool,
)


orders = {
    "O-1001": {"order_id": "O-1001", "status": "shipped", "eta": "2026-05-20"},
}


@tool(
    "lookup_order",
    "Look up an order by order ID and return its status as JSON.",
    {"order_id": str},
    annotations=ToolAnnotations(readOnlyHint=True),
)
async def lookup_order(args):
    order_id = args["order_id"]
    order = orders.get(order_id)

    if order is None:
        return {
            "is_error": True,
            "content": [{"type": "text", "text": f"Order not found: {order_id}"}]
        }

    return {"content": [{"type": "text", "text": json.dumps(order)}]}


order_tools = create_sdk_mcp_server(
    name="orders",
    tools=[lookup_order],
)


async def main():
    options = QoderAgentOptions(
        auth=qodercli_auth(),
        mcp_servers={"orders": order_tools},
        allowed_tools=["mcp__orders__lookup_order"],
    )

    async for message in query(
        prompt="Check the status of order O-1001 and summarize it in one sentence.",
        options=options,
    ):
        print(message)


asyncio.run(main())

```

--------------------------------

### PIP Package Installation Example

Source: https://docs.qoder.com/cloud-agents/api/environments/schemas

Specifies Python packages to be installed using 'pip install'. Example includes pandas and PyYAML with a specific version.

```javascript
pip
```

```javascript
array of string
```

```javascript
pip install
```

```javascript
[\"pandas\", \"PyYAML==6.0.1\"]
```

--------------------------------

### Initialize and Connect to Qoder SDK Client

Source: https://docs.qoder.com/en/cli/sdk/python/agents

Demonstrates how to initialize the QoderSDKClient with options, connect to the service, and list available agents. Ensure you have the necessary imports.

```python
from qoder_agent_sdk import QoderSDKClient, QoderAgentOptions

client = QoderSDKClient(options=QoderAgentOptions())
await client.connect("List available agents.")
agents = client.supported_agents()
await client.disconnect()
```

--------------------------------

### Environment Configuration with Preinstalled Packages

Source: https://docs.qoder.com/cloud-agents/environments

This example shows how to configure an environment with specific system (apt), Python (pip), and Node.js (npm) packages preinstalled. Be mindful that preinstalled packages increase environment startup time.

```json
{
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"},
    "packages": {
      "apt": ["git", "build-essential", "libssl-dev"],
      "pip": ["pandas", "numpy", "scikit-learn"],
      "npm": ["typescript", "eslint", "prettier"]
    }
  }
}
```

--------------------------------

### Python SDK Agent Options Example

Source: https://docs.qoder.com/en/cli/sdk/python/tools

Demonstrates how to initialize QoderAgentOptions with authentication, current working directory, and allowed tools. This is useful for setting up agent configurations.

```python
import asyncio

from qoder_agent_sdk import QoderAgentOptions, qodercli_auth, query

async def main():
    options = QoderAgentOptions(
        auth=qodercli_auth(),
        cwd="/path/to/project",
        tools=["Read"]
    )
```

--------------------------------

### Minimal QoderSDKClient Example

Source: https://docs.qoder.com/en/cli/sdk/python/quick-start

This snippet demonstrates the basic initialization of the QoderSDKClient. Ensure you have the necessary imports and QoderAgentOptions configured.

```python
import anyio

from qoder_agent_sdk import (
    AssistantMessage,
    QoderAgentOptions,
    QoderSDKClient,
    TextBlock,
    access_token_from_env,
)

async def main():
    options = QoderAgentOptions(

```

--------------------------------

### End-to-End Qoder Cloud Agents Quickstart Script

Source: https://docs.qoder.com/llms-full.txt

This bash script automates the setup and interaction with Qoder Cloud Agents. It requires a QODER_PAT environment variable for authentication. The script fetches or creates an environment and an agent, initiates a session, sends a user message, and streams the agent's responses.

```bash
#!/bin/bash
# Qoder Cloud Agents quickstart script
# Usage: export QODER_PAT="your-token" && bash quickstart.sh

set -euo pipefail

BASE_URL="https://api.qoder.com/api/v1/cloud"
HEADERS=(
  -H "Authorization: Bearer $QODER_PAT"
)

echo "=== Step 1: Fetch environment ==="
ENV_ID=$(curl -s "$BASE_URL/environments" "${HEADERS[@]}" | jq -r '.data[0].id')
if [ "$ENV_ID" = "null" ] || [ -z "$ENV_ID" ]; then
  echo "No environment found. Creating a default one..."
  ENV_ID=$(curl -s -X POST "$BASE_URL/environments" \
    "${HEADERS[@]}" \
    -H "Content-Type: application/json" \
    -d '{"name":"default","config":{"type":"cloud","networking":{"type":"unrestricted"}}}' | jq -r '.id')
fi
echo "Environment ID: $ENV_ID"

echo "=== Step 2: Get or create the Agent ==="
AGENT_ID=$(curl -s "$BASE_URL/agents" "${HEADERS[@]}" | jq -r '.data[0].id')
if [ "$AGENT_ID" = "null" ] || [ -z "$AGENT_ID" ]; then
  AGENT_ID=$(curl -s -X POST "$BASE_URL/agents" \
    "${HEADERS[@]}" \
    -H "Content-Type: application/json" \
    -d '{ \
      "name": "quickstart-agent", \
      "model": "ultimate", \
      "system": "You are an efficient programming assistant.", \
      "tools": [{"type": "agent_toolset_20260401", "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]}] \
    }' | jq -r '.id')
fi
echo "Agent ID: $AGENT_ID"

echo "=== Step 3: Create the Session ==="
SESSION_ID=$(curl -s -X POST "$BASE_URL/sessions" \
  "${HEADERS[@]}" \
  -H "Content-Type: application/json" \
  -d "{\"agent\": \"$AGENT_ID\", \"environment_id\": \"$ENV_ID\"}" | jq -r '.id')
echo "Session ID: $SESSION_ID"

echo "=== Step 4: Send a message ==="
curl -s -X POST "$BASE_URL/sessions/$SESSION_ID/events" \
  "${HEADERS[@]}" \
  -H "Content-Type: application/json" \
  -d '{ \
    "events": [ \
      {"type": "user.message", "content": [{"type": "text", "text": "Print Hello World and tell me the current system time."}]} \
    ] \
  }' | jq .

echo "=== Step 5: Stream events ==="
echo "(Press Ctrl+C to exit)"
curl -s -N "$BASE_URL/sessions/$SESSION_ID/events/stream" "${HEADERS[@]}"
```

--------------------------------

### Get Member Statistics Response Example

Source: https://docs.qoder.com/account/teams/openapi/members

Example JSON response for the member statistics endpoint, showing the total number of members.

```json
{
  "totalMembers": 150
}
```

--------------------------------

### Example Session Configuration

Source: https://docs.qoder.com/cloud-agents/sessions

Illustrates a sample session configuration with environment variables. Ensure variable names adhere to the specified format and constraints.

```javascript
{
  "session_variables": {
    "production": "1",
    "FEATURE_FLAG": "1"
  }
}
```

--------------------------------

### Install Extra Software with Packages

Source: https://docs.qoder.com/cloud-agents/container-reference

Use the Environment's 'packages' field to install additional dependencies. This JSON snippet shows an example of how to specify packages.

```json
{
  "packages": [
    "git",
    "curl",
    "vim"
  ]
}
```

--------------------------------

### Python SDK Skill Management Example

Source: https://docs.qoder.com/en/cli/sdk/python/skills

Demonstrates how to initialize the Qoder SDK client, fetch server information, and iterate through skills. Ensure the SDK is initialized with appropriate options.

```python
async with QoderSDKClient(options) as client:
    info = await client.get_server_info()
    if info:
        for skill in info.get("skills", []):
            print(skill["name"], skill.get("description", ""))
```

--------------------------------

### Making a GET Request with Authentication

Source: https://docs.qoder.com/cloud-agents/api/conventions/authentication

Example of making a GET request to retrieve data using an authenticated client. This demonstrates how the API key is used implicitly.

```javascript
async function getAccountInfo() {
  try {
    const account = await client.accounts.get("me");
    console.log(account);
  } catch (error) {
    console.error("Error fetching account info:", error);
  }
}
```

--------------------------------

### Minimal Custom Tool Integration Example

Source: https://docs.qoder.com/en/cli/sdk/tools

This is a complete, minimal example demonstrating the integration of a custom tool. It includes necessary imports and setup for an MCP server.

```typescript
import {
  accessTokenFromEnv,
  createSdkMcpServer,
  tool
} from "@qoder/sdk";

// Define a custom tool
const myTool = tool({
  name: "myTool",
  description: "A simple custom tool.",
  parameters: {
    type: "object",
    properties: {
      message: {
        type: "string",
        description: "A message to be echoed."
      }
    },
    required: ["message"]
  },
  func: async ({ message }) => {
    return { message };
  }
});

// Create an MCP server with the custom tool
const mcpServer = createSdkMcpServer({
  tools: [myTool],
  // You can optionally provide a custom access token resolver
  // accessToken: accessTokenFromEnv(),
});

// Example of how to use the MCP server with a query
// const query = async () => {
//   const response = await mcpServer.query({
//     messages: [
//       {
//         role: "user",
//         content: "Call myTool with message: Hello Qoder!"
//       }
//     ],
//     options: {
//       // You can control tool access with permission settings
//       // permissions: {
//       //   allow: ["myTool"]
//       // }
//     }
//   });
//   console.log(response);
// };

// query();

```

--------------------------------

### Multi-tool SDK Server Example

Source: https://docs.qoder.com/llms-full.txt

Demonstrates setting up an SDK MCP server with multiple tools, including a `searchDocs` tool for querying internal documentation and a `queryDb` tool.

```typescript
const searchDocs = tool(
  'search_docs',
  'Search internal docs and return relevant snippets.',
  {
    query: z.string().describe('Search keywords'),
    maxResults: z.number().int().min(1).max(20).optional()
      .describe('Maximum number of results, defaults to 5'),
  },
  async ({ query, maxResults = 5 }) => {
    const hits = await docs.search(query, maxResults);
    return { content: [{ type: 'text', text: JSON.stringify(hits) }] };
  },
  { annotations: { readOnlyHint: true } },
);

const server = createSdkMcpServer({
  name: 'kb',
  tools: [searchDocs, queryDb /* ... */],
});
```

--------------------------------

### Example Agent Query and Options

Source: https://docs.qoder.com/en/cli/sdk/python/agents

Demonstrates how to call an agent with a specific prompt and configure options. Ensure 'Agent' is included in both `allowed_tools` and `tools` if restricting tool usage.

```python
print(Agent(
  query("Use the Explore agent to find where authentication is implemented.",
  options=options,
):
    print(message)
```

--------------------------------

### Get File Extension Statistics

Source: https://docs.qoder.com/account/teams/openapi/ai-code-metrics

Fetches statistics related to file extensions for AI code contributions starting from a specified date. Requires organization ID and a start date.

```bash
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/ai-code/file-extensions?start_date=2025-06-01T00:00:00Z" \
  -H "Authorization: Bearer <api_key>"
```

--------------------------------

### Create Session with Tools

Source: https://docs.qoder.com/cloud-agents/api/sessions/create

This example demonstrates creating a session with specific tools enabled. Ensure the tools are correctly formatted and available.

```javascript
const createSessionWithTools = async (agentId, model, prompt, tools) => {
  const response = await fetch('/api/sessions/create', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      agent_id: agentId,
      model: model,
      prompt: prompt,
      tools: tools
    })
  });
  return response.json();
};
```

--------------------------------

### Multi-File Skill SKILL.md Example

Source: https://docs.qoder.com/llms-full.txt

This example demonstrates a SKILL.md file for a database migration tool that utilizes multiple scripts and external files. It includes setup instructions and workflow details.

```markdown
---
name: database-migrator
description: Generate and manage database migrations, schema changes, and data transformations. Use when creating migrations, modifying database schema, or managing database versions. Requires sqlalchemy and alembic packages.
---

# Database Migrator

## Quick start

Generate a new migration:

```bash
python scripts/generate_migration.py --name add_user_table
```

For detailed migration patterns, see [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md).
For rollback strategies, see [ROLLBACK.md](ROLLBACK.md).

## Workflow

1. **Analyze changes**: Compare current schema with desired state
2. **Generate migration**: Create migration file with up/down operations
3. **Validate**: Run `python scripts/validate_schema.py` to check syntax
4. **Backup**: Execute `scripts/backup_db.sh` before applying
5. **Apply**: Run migration in staging environment first
6. **Verify**: Check data integrity after migration

## Requirements

Install required packages:
```bash
pip install sqlalchemy alembic psycopg2-binary
```

## Safety checks

- Always backup before migrations
- Test rollback procedures
- Validate data integrity after changes
- Use transactions for atomic operations

```

--------------------------------

### Configure Qoder SDK Client Options

Source: https://docs.qoder.com/en/cli/sdk/python/tools

Example of initializing QoderSDKClient with authentication, MCP servers, and allowed tools for multi-turn sessions.

```python
from qoder_agent_sdk import QoderSDKClient

options = QoderAgentOptions(
    auth=qodercli_auth(),
    mcp_servers={"kb": kb_tools},
    allowed_tools=["mcp__kb__search_docs"],

```

--------------------------------

### Session Running SSE Event

Source: https://docs.qoder.com/llms-full.txt

Example of a 'session.status_running' event. This indicates that the session has started processing.

```text
id: evt_771c1195bcbd4a07834d4ed4dd6450ca
event: session.status_running
data: {"id": "evt_771c1195bcbd4a07834d4ed4dd6450ca", "type": "session.status_running", "turn_id": "turn_019e392c0d787ceea6bb62943f9ac3ec", "created_at": "2026-05-18T03:40:50.321Z", "session_id": "sess_019e392c0d1e74e095d21ea4c6b41def", "processed_at": "2026-05-18T03:40:50.321Z", "schema_version": "1.0"}
```

--------------------------------

### Get a session by ID

Source: https://docs.qoder.com/cloud-agents/api/sessions/get

This example demonstrates how to retrieve session details using the session ID.

```APIDOC
## GET /cloud-agents/api/sessions/get

### Description
Retrieve the full details of a single session by ID.

### Method
GET

### Endpoint
/cloud-agents/api/sessions/get

### Parameters
#### Query Parameters
- **id** (string) - Required - The unique identifier of the session to retrieve.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the session.
- **title** (string) - The title of the session.
- **metadata** (object) - Key-value pairs for additional session information.
- **createdAt** (string) - The timestamp when the session was created.
- **updatedAt** (string) - The timestamp when the session was last updated.
- **archivedAt** (string) - The timestamp when the session was archived, if applicable.
- **cancelledAt** (string) - The timestamp when the session was cancelled, if applicable.

#### Response Example
```json
{
  "id": "sess_abc123xyz789",
  "title": "My Session Title",
  "metadata": {
    "key1": "value1",
    "key2": "value2"
  },
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T10:30:00Z",
  "archivedAt": null,
  "cancelledAt": null
}
```
```

--------------------------------

### Initialize QoderSDKClient with Plan Mode

Source: https://docs.qoder.com/en/cli/sdk/python/permissions

Demonstrates how to initialize the QoderSDKClient in 'plan' permission mode. This mode requires explicit definition of allowed actions. Ensure the 'qoder_agent_sdk' is installed.

```python
from qoder_agent_sdk import QoderSDKClient


async with QoderSDKClient(
    options=QoderAgentOptions(
        cwd="/path/to/project",
        permission_mode="plan",
    )
) as client:
```

--------------------------------

### Get Member Details

Source: https://docs.qoder.com/account/teams/openapi/members

Example of retrieving details for a specific member, including their status and join date.

```json
{
  "id": "member_def456",
  "name": "Bob",
  "email": "bob@example.com",
  "role": "org_member",
  "joinedAt": "2025-06-01T08:00:00Z"
}
```

--------------------------------

### Using kb_tools

Source: https://docs.qoder.com/en/cli/sdk/python/tools

This snippet demonstrates how to initialize the QoderSDKClient and use the `kb_tools` to query for information.

```APIDOC
## Using kb_tools

### Description
This section shows how to initialize the QoderSDKClient and use the `kb_tools` to perform queries.

### Initialization
```python
async with QoderSDKClient(options) as client:
    await client.query("Search docs for the refund policy.")
```

### Receiving Responses
```python
async for message in client.receive_response():
    print(message)
```
```

--------------------------------

### Plugin Configuration Example

Source: https://docs.qoder.com/en/cli/sdk/plugins

Illustrates how to configure plugins, specifying their type and path. This is useful for integrating local or remote plugins into the SDK.

```javascript
{
  "plugins": [
    {
      "type": "local",
      "path": "/path/to/plugin-a" 
    },
    {
      "type": "local",
      "path": "/path/to/plugin-b" 
    }
  ]
}
```

--------------------------------

### Initialize and Use MCP SDK

Source: https://docs.qoder.com/en/cli/sdk/python/mcp

Demonstrates how to initialize the MCP SDK and use its components. Ensure all necessary components are imported and provided.

```javascript
self.__next_f.push([1, "\
```

```javascript
use strict\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n blockquote: \"blockquote\",\n code: \"code\",\n li: \"li\",\n ol: \"ol\",\n p: \"p\",\n pre: \"pre\",\n span: \"span\",\n strong: \"strong\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ul: \"ul\",\n ..._provideComponents(),\n ...props.components\n }, {CodeBlock, Heading, Table} = _components;\n if (!CodeBlock) _missingMdxReference(\"CodeBlock\", true);\n if (!Heading) _missingMdxReference(\"Heading\", true);\n if (!Table) _missingMdxReference(\"Table\", true);\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"MCP (Model Context Protocol) is an open protocol for AI Agents to invoke external tools. "\n })]\n })\n}\n
```

--------------------------------

### Minimal example: query()

Source: https://docs.qoder.com/en/cli/sdk/python/quick-start

This is a minimal example demonstrating the `query()` function. It's suitable for one-shot, stateless tasks where you send a single prompt and get a result. The function is an async generator that finishes when the process ends.

```python
import qoder

async def main():
    response = await qoder.query("What is the capital of France?", {
        "model": "gpt-3.5-turbo"
    })
    print(response)

import asyncio
asyncio.run(main())
```

--------------------------------

### QoderSDKClient Initialization and Usage

Source: https://docs.qoder.com/en/cli/sdk/python/references

Demonstrates how to initialize the Qoder SDK client with options, connect to the service, list supported agents, and disconnect.

```APIDOC
## QoderSDKClient Initialization and Usage

### Description
This section details the initialization of the `QoderSDKClient`, establishing a connection, retrieving a list of supported agents, and disconnecting from the service.

### Initialization
```python
client = QoderSDKClient(options)
```

### Connection
Establishes a connection to the Qoder service. This method can be used to list agents.

```python
await client.connect("List agents.")
```

### Agent Listing
Retrieves a list of agents supported by the client. This list may include built-in, project, user, or plugin agents.

```python
agents = client.supported_agents()
```

### Disconnection
Closes the connection to the Qoder service.

```python
await client.disconnect()
```

### Parameters
#### Initialization Options
- **options** (object) - Configuration options for the client.

#### Connection Parameters
- **prompt** (string) - A prompt to guide the connection process, potentially for agent listing.

### Response
#### Agent Listing Response
- **agents** (list) - A list of supported agent identifiers.
```

--------------------------------

### Get AI Code Metrics

Source: https://docs.qoder.com/account/teams/openapi/ai-code-metrics

Retrieves AI-generated code metrics. You can filter the results by specifying a start and end date.

```APIDOC
## GET /ai/code/metrics

### Description
Retrieves AI-generated code metrics. You can filter the results by specifying a start and end date.

### Method
GET

### Endpoint
/ai/code/metrics

### Parameters
#### Query Parameters
- **organization_id** (string) - Yes - Organization ID
- **start_date** (string) - No - Start time
- **end_date** (string) - No - End time

### Response
#### Success Response (200 OK)
- **fileExtensions** (array) - List of file extensions with their associated metrics.
  - **extension** (string) - The file extension (e.g., ".go").
  - **changeCount** (integer) - The number of changes for this extension.
  - **totalLinesAdded** (integer) - The total number of lines added for this extension.

### Response Example
```json
{
  "fileExtensions": [
    {
      "extension": ".go",
      "changeCount": 500,
      "totalLinesAdded": 12000
    }
  ]
}
```
```

--------------------------------

### Basic query() usage

Source: https://docs.qoder.com/en/cli/sdk/python/quick-start

This example demonstrates a basic call to the `query()` function with a prompt and options. Ensure the `qoder` library is installed and configured.

```python
import qoder

# Example usage of query()
# This is a placeholder for actual code execution
# The actual code would involve calling query with prompt and options
# For demonstration, we'll represent the structure

# Placeholder for the query function call structure
# query("prompt", options)

# The following is a representation of how the code might look like in a script:
# from qoder import query
# 
# async def main():
#     response = await query("Hello", {"model": "gpt-3.5-turbo"})
#     print(response)
# 
# import asyncio
# asyncio.run(main())

# The provided snippet is a JSX representation of code, not direct Python code.
# Below is a Python code snippet that represents the intent of the JSX.

from qoder import query

async def run_query():
    response = await query("Hello", {
        "options": {
            "model": "gpt-3.5-turbo"
        }
    })
    print(response)

# To run this, you would typically use an async event loop:
# import asyncio
# asyncio.run(run_query())

```

--------------------------------

### Minimal example: QoderSDKClient

Source: https://docs.qoder.com/en/cli/sdk/python/quick-start

A minimal example showing how to instantiate and use `QoderSDKClient` for API calls. This client provides a more object-oriented approach.

```python
from qoder_sdk import QoderSDKClient

client = QoderSDKClient()
response = client.query(
    """
    query {
      users {
        id
        name
      }
    }
    """
)
print(response)
```

--------------------------------

### Install Python Packages in Environment

Source: https://docs.qoder.com/cloud-agents/environments

Example of specifying Python packages to be pre-installed in an environment. Ensure correct JSON formatting for the package list.

```json
{
  "pip": [
    "pandas",
    "numpy",
    "matplotlib",
    "scikit-learn",
    "jupyter",
    "sqlalchemy"
  ]
}
```

--------------------------------

### Get Supported Agents from Plugins

Source: https://docs.qoder.com/en/cli/sdk/plugins

Retrieves a list of all supported agents contributed by installed plugins. This can be used to discover and list available agents.

```javascript
const agents = await q.supportedAgents();
console.log(agents.map((agent) => agent.name));
```

--------------------------------

### Initialize and Query Agent

Source: https://docs.qoder.com/en/cli/sdk/python/agents

Demonstrates how to initialize a Qoder agent with options and then query it for a specific task. This is useful for setting up agent behavior and retrieving information.

```python
from qoder.agents import QoderAgentOptions, query

options = QoderAgentOptions(
    agent="general-purpose"
)

async for message in query(
    prompt="Summarize this project architecture and identify the most important modules.",
    options=options,
):
    print(message)
```