### Scope Configuration Examples

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Demonstrates how to define granular permissions for toolkit operations using the Scope and Product system. Includes examples for read-only access, full expense management, enabling all tools, and creating configurations from tool strings.

```python
from extend_ai_toolkit.shared import Configuration, Scope, Product, Actions

# Available Products:
# - Product.VIRTUAL_CARDS: Virtual card operations
# - Product.CREDIT_CARDS: Credit card operations
# - Product.TRANSACTIONS: Transaction operations
# - Product.EXPENSE_CATEGORIES: Expense category management
# - Product.RECEIPT_ATTACHMENTS: Receipt upload and matching

# Available Actions:
# - read: View/list resources
# - create: Create new resources
# - update: Modify existing resources

# Example: Read-only access to cards and transactions
read_only_config = Configuration(
    scope=[
        Scope(Product.VIRTUAL_CARDS, actions=Actions(read=True)),
        Scope(Product.CREDIT_CARDS, actions=Actions(read=True)),
        Scope(Product.TRANSACTIONS, actions=Actions(read=True)),
    ]
)

# Example: Full access to expense management
expense_management_config = Configuration(
    scope=[
        Scope(Product.TRANSACTIONS, actions=Actions(read=True, update=True)),
        Scope(Product.EXPENSE_CATEGORIES, actions=Actions(read=True, create=True, update=True)),
        Scope(Product.RECEIPT_ATTACHMENTS, actions=Actions(read=True, create=True)),
    ]
)

# Example: Enable all available tools
all_tools_config = Configuration.all_tools()

# Example: Create configuration from tool string (useful for CLI)
config_from_str = Configuration.from_tool_str("virtual_cards.read,transactions.read,credit_cards.read")
```

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

### Install extend_ai_toolkit

Source: https://github.com/paywithextend/extend-ai-toolkit/blob/development/README.md

Install the Extend AI Toolkit package using pip. Requires Python 3.10 or higher.

```sh
pip install extend_ai_toolkit
```

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

### Run MCP Server with SSE Transport

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Start the server in SSE mode and connect using the terminal client.

```bash
# Start the SSE server
python -m extend_ai_toolkit.modelcontextprotocol.main_sse --tools=all --api-key="apikey" --api-secret="apisecret"

# Connect using the MCP terminal client
python -m extend_ai_toolkit.modelcontextprotocol.client.mcp_client \
    --mcp-server-host localhost \
    --mcp-server-port 8000 \
    --llm-provider=anthropic \
    --llm-model=claude-3-5-sonnet-20241022
```

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

### Configure Claude Desktop MCP Server

Source: https://github.com/paywithextend/extend-ai-toolkit/blob/development/README.md

Add this tool as an MCP server to Claude Desktop by editing the config file. Ensure the filesystem MCP server is installed if using the create_receipt_attachment tool.

```json
{
  "extend-mcp": {
    "command": "python",
    "args": [
      "-m",
      "extend_ai_toolkit.modelcontextprotocol.main",
      "--tools=all"
    ],
    "env": {
      "EXTEND_API_KEY": "apik_XXXX",
      "EXTEND_API_SECRET": "XXXXX"
    }
  },
  // optional: if you want to use the create_receipt_attachment tool
  "filesystem": {
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-filesystem",
      "/path/to/receipts/folder"
    ]
  }
}
```

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

### Run Extend AI Toolkit Server Remotely via SSE

Source: https://github.com/paywithextend/extend-ai-toolkit/blob/development/README.md

Execute your server remotely and communicate via SSE transport. This command starts the main SSE server with all tools enabled.

```bash
python -m extend_ai_toolkit.modelcontextprotocol.main_sse --tools=all --api-key="apikey" --api-secret="apisecret"
```

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

### Import necessary libraries

Source: https://github.com/paywithextend/extend-ai-toolkit/blob/development/extend_ai_toolkit/notebooks/langchain-react-agent.ipynb

Imports required libraries for interacting with Extend AI, Langchain, and asynchronous operations. Ensure you have these installed.

```python
import os
import asyncio
from dotenv import load_dotenv

from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent
from langchain_core.messages import SystemMessage, AIMessage, HumanMessage

from extend_ai_toolkit.langchain.toolkit import ExtendLangChainToolkit
from extend_ai_toolkit.shared import Configuration, Scope, Product, Actions

from IPython.display import display, clear_output
import ipywidgets as widgets

import nest_asyncio
nest_asyncio.apply()
```

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

### Retrieve credit card details

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Get detailed information for a specific credit card.

```python
from extend_ai_toolkit.shared import ExtendAPI

extend_api = ExtendAPI.default_instance(api_key="apik_xxx", api_secret="secret")

# Get detailed information about a specific credit card
result = await extend_api.run(
    "get_credit_card_detail",
    credit_card_id="cc_xyz789"
)

print(result)  # Returns card details, limits, associated virtual cards, etc.
```

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

### Retrieve virtual card details

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Get detailed information for a specific virtual card by ID.

```python
from extend_ai_toolkit.shared import ExtendAPI

extend_api = ExtendAPI.default_instance(api_key="apik_xxx", api_secret="secret")

# Get detailed information about a specific virtual card
result = await extend_api.run(
    "get_virtual_card_detail",
    virtual_card_id="vc_abc123def456"
)

# Response includes: card details, balance, status, recipient info, limits, etc.
print(result)
```

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

### Test Extend MCP Server Locally

Source: https://github.com/paywithextend/extend-ai-toolkit/blob/development/README.md

Test your Extend MCP server locally using the MCP Inspector. Ensure you have the necessary tools installed.

```bash
npx @modelcontextprotocol/inspector python extend_ai_toolkit/modelcontextprotocol/main.py --tools=all
```

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

### Get Transaction Detail

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Retrieves detailed information about a specific transaction.

```APIDOC
## GET /transactions/{transaction_id}

### Description
Retrieve detailed information about a specific transaction including expense data and receipt status.

### Method
GET

### Endpoint
/transactions/{transaction_id}

### Parameters
#### Path Parameters
- **transaction_id** (string) - Required - The unique identifier of the transaction.

### Response
#### Success Response (200)
- **amount** (number) - The transaction amount.
- **merchant** (string) - The merchant name.
- **date** (string) - The transaction date.
- **status** (string) - The transaction status.
- **expense_categories** (array) - List of associated expense categories.
- **receipts** (array) - List of associated receipts.

### Response Example
```json
{
  "id": "txn_abc123",
  "amount": 75.50,
  "merchant": "Example Corp",
  "date": "2023-10-26",
  "status": "pending",
  "expense_categories": [
    {
      "categoryId": "cat_travel",
      "labelId": "lbl_flights"
    }
  ],
  "receipts": [
    {
      "receiptId": "rec_def456"
    }
  ]
}
```
```

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

### Get Expense Categories

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Retrieves all expense categories configured for the organization.

```APIDOC
## GET /expense_categories

### Description
Retrieve all expense categories configured for the organization.

### Method
GET

### Endpoint
/expense_categories

### Query Parameters
- **active** (boolean) - Optional - Filter by active status.
- **required** (boolean) - Optional - Filter by required status.
- **search** (string) - Optional - Search term for categories.
- **sort_field** (string) - Optional - Field to sort by (e.g., 'name').
- **sort_direction** (string) - Optional - Sort direction ('ASC' or 'DESC').

### Response
#### Success Response (200)
- **categories** (array) - A list of expense categories.

### Response Example
```json
{
  "categories": [
    {
      "id": "cat_travel",
      "name": "Travel",
      "code": "TRVL",
      "required": false,
      "active": true,
      "free_text_allowed": false
    }
  ]
}
```
```

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

### Define and execute asynchronous chat function

Source: https://github.com/paywithextend/extend-ai-toolkit/blob/development/extend_ai_toolkit/notebooks/langchain-react-agent.ipynb

Defines an asynchronous function 'chat_with_agent' to interact with the Langchain agent. It sends a series of predefined messages and prints the agent's responses. The function is then called to start the chat.

```python
async def chat_with_agent():
    print("\nWelcome to the Extend AI Assistant!")
    print("I'll send a sequence of predefined messages to the agent and show the responses.\n")
    
    # Define the messages to send
    messages = [
        "please show me transactions from feb 2025 from langchain inc",
        "please tell me about my expense categories and labels",
        "please tell me which transactions from feb 2025 are missing receipts"    ]
    
    # Send each message and print the response
    for i, user_input in enumerate(messages, 1):
        print(f"\n--- Message {i}: {user_input} ---")
        print("Assistant: ", end="", flush=True)
        
        # Process the query
        result = await langgraph_agent_executor.ainvoke({
            "input": user_input,
            "messages": [
                SystemMessage(content="You are a helpful assistant that can interact with the Extend API to manage virtual cards, credit cards, and transactions."),
                HumanMessage(content=user_input)
            ]
        })
        
        # Extract and print the assistant's message
        for message in result.get('messages', []):
            if isinstance(message, AIMessage):
                print(message.content)
        
        # Add a separator between messages
        print("\n" + "-" * 50)
    
    print("\nAll messages have been processed.")
```

```python
await chat_with_agent()
```

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

### Retrieve specific expense category

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Gets detailed information for a single expense category by ID.

```python
from extend_ai_toolkit.shared import ExtendAPI

extend_api = ExtendAPI.default_instance(api_key="apik_xxx", api_secret="secret")

# Get specific expense category details
result = await extend_api.run(
    "get_expense_category",
    category_id="cat_travel"
)

print(result)  # Returns category name, code, required status, labels, etc.
```

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

### Get Expense Category

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Retrieves detailed information about a specific expense category.

```APIDOC
## GET /expense_categories/{category_id}

### Description
Retrieve detailed information about a specific expense category.

### Method
GET

### Endpoint
/expense_categories/{category_id}

### Parameters
#### Path Parameters
- **category_id** (string) - Required - The unique identifier of the expense category.

### Response
#### Success Response (200)
- **id** (string) - The category ID.
- **name** (string) - The category name.
- **code** (string) - The category code.
- **required** (boolean) - Whether the category is required.
- **active** (boolean) - Whether the category is active.
- **free_text_allowed** (boolean) - Whether free text is allowed.
- **labels** (array) - List of associated labels.

### Response Example
```json
{
  "id": "cat_travel",
  "name": "Travel",
  "code": "TRVL",
  "required": false,
  "active": true,
  "free_text_allowed": false,
  "labels": [
    {
      "id": "lbl_flights",
      "name": "Flights"
    }
  ]
}
```
```

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

### Get Automatch Status API

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Check the status of a receipt automatch job.

```APIDOC
## GET /paywithextend/extend-ai-toolkit/get_automatch_status

### Description
Check the status of a receipt automatch job.

### Method
GET

### Endpoint
/paywithextend/extend-ai-toolkit/get_automatch_status

### Parameters
#### Query Parameters
- **job_id** (string) - Required - The ID of the automatch job to check.

### Response
#### Success Response (200)
- **status** (string) - The current status of the job (e.g., PENDING, IN_PROGRESS, COMPLETED, FAILED).
- **matchedReceipts** (array of objects) - A list of successfully matched receipts.
- **unmatchedReceipts** (array of objects) - A list of receipts that could not be matched.

#### Response Example
```json
{
  "status": "COMPLETED",
  "matchedReceipts": [
    {
      "receiptId": "rcpt_abc123",
      "transactionId": "txn_abc123"
    }
  ],
  "unmatchedReceipts": [
    {
      "receiptId": "rcpt_def456",
      "reason": "No matching transaction found"
    }
  ]
}
```
```

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

### Get Expense Category Labels

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Retrieves labels associated with a specific expense category.

```APIDOC
## GET /expense_categories/{category_id}/labels

### Description
Retrieve labels associated with a specific expense category.

### Method
GET

### Endpoint
/expense_categories/{category_id}/labels

### Parameters
#### Path Parameters
- **category_id** (string) - Required - The unique identifier of the expense category.

### Query Parameters
- **active** (boolean) - Optional - Filter by active status.
- **search** (string) - Optional - Search term for labels.
- **sort_field** (string) - Optional - Field to sort by (e.g., 'name').
- **sort_direction** (string) - Optional - Sort direction ('ASC' or 'DESC').
- **page** (integer) - Optional - Page number for pagination.
- **per_page** (integer) - Optional - Number of items per page.

### Response
#### Success Response (200)
- **labels** (array) - A list of labels associated with the category.

### Response Example
```json
{
  "labels": [
    {
      "id": "lbl_flights",
      "name": "Flights",
      "active": true
    }
  ]
}
```
```

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

### Get Automatch Status

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Checks the status of a receipt automatch job using its job ID. Provides details on matched and unmatched receipts.

```python
from extend_ai_toolkit.shared import ExtendAPI

extend_api = ExtendAPI.default_instance(api_key="apik_xxx", api_secret="secret")

# Check automatch job status
result = await extend_api.run(
    "get_automatch_status",
    job_id="job_xyz789"
)

# Response includes:
# - status: PENDING, IN_PROGRESS, COMPLETED, FAILED
# - matchedReceipts: List of successfully matched receipts
# - unmatchedReceipts: List of receipts that couldn't be matched
print(result)
```

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

### Initialize LLM, Extend Toolkit, and Agent

Source: https://github.com/paywithextend/extend-ai-toolkit/blob/development/extend_ai_toolkit/notebooks/langchain-react-agent.ipynb

Initializes the ChatOpenAI language model, the ExtendLangChainToolkit with specific configurations for products and actions, and creates a React agent executor.

```python
llm = ChatOpenAI(
    model="gpt-4o",
)

extend_langchain_toolkit = ExtendLangChainToolkit.default_instance(
    api_key,
    api_secret,
    Configuration(
      scope=[
        Scope(Product.VIRTUAL_CARDS, actions=Actions(read=True,update=True)),
        Scope(Product.CREDIT_CARDS, actions=Actions(read=True)),
        Scope(Product.TRANSACTIONS, actions=Actions(read=True,update=True)),
        Scope(Product.EXPENSE_CATEGORIES, actions=Actions(read=True)),
        Scope(Product.RECEIPT_ATTACHMENTS, actions=Actions(read=True)),
       ]
    )
)

tools = []
tools.extend(extend_langchain_toolkit.get_tools())

# Create the react agent
langgraph_agent_executor = create_react_agent(
    llm,
    tools
)
```

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

### Build LangChain ReAct Agent with Extend Tools

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Initialize an LLM and the Extend LangChain toolkit with specific scopes and actions. Then, create a ReAct agent and execute it with a query to interact with the Extend API.

```python
import os
import asyncio
from dotenv import load_dotenv

from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent
from langchain_core.messages import SystemMessage, AIMessage, HumanMessage

from extend_ai_toolkit.langchain.toolkit import ExtendLangChainToolkit
from extend_ai_toolkit.shared import Configuration, Scope, Product, Actions

load_dotenv()

async def main():
    # Initialize LLM
    llm = ChatOpenAI(model="gpt-4o")

    # Initialize the LangChain toolkit
    extend_langchain_toolkit = ExtendLangChainToolkit.default_instance(
        api_key=os.environ.get("EXTEND_API_KEY"),
        api_secret=os.environ.get("EXTEND_API_SECRET"),
        configuration=Configuration(
            scope=[
                Scope(Product.VIRTUAL_CARDS, actions=Actions(read=True, update=True)),
                Scope(Product.CREDIT_CARDS, actions=Actions(read=True)),
                Scope(Product.TRANSACTIONS, actions=Actions(read=True, update=True)),
                Scope(Product.EXPENSE_CATEGORIES, actions=Actions(read=True)),
                Scope(Product.RECEIPT_ATTACHMENTS, actions=Actions(read=True)),
            ]
        )
    )

    # Get tools and create the ReAct agent
    tools = extend_langchain_toolkit.get_tools()
    langgraph_agent_executor = create_react_agent(llm, tools)

    # Run the agent with a query
    result = await langgraph_agent_executor.ainvoke({
        "input": "Show me recent transactions over $100",
        "messages": [
            SystemMessage(content="You are a helpful assistant that can interact with the Extend API to manage virtual cards, credit cards, and transactions."),
            HumanMessage(content="Show me recent transactions over $100")
        ]
    })

    # Print the assistant's response
    for message in result.get('messages', []):
        if isinstance(message, AIMessage):
            print("Assistant:", message.content)

if __name__ == "__main__":
    asyncio.run(main())

```

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

### Initialize Extend OpenAI Toolkit

Source: https://github.com/paywithextend/extend-ai-toolkit/blob/development/README.md

Initialize the Extend OpenAI toolkit with API keys and a specific configuration scope. This sets up the necessary components for integrating Extend with OpenAI.

```python
import os
from langchain_openai import ChatOpenAI
from extend_ai_toolkit.openai.toolkit import ExtendOpenAIToolkit
from extend_ai_toolkit.shared import Configuration, Scope, Product, Actions

# Initialize the OpenAI toolkit
extend_openai_toolkit = ExtendOpenAIToolkit.default_instance(
    api_key=os.environ.get("EXTEND_API_KEY"),
    api_secret=os.environ.get("EXTEND_API_SECRET"),
    configuration=Configuration(
        scope=[
            Scope(Product.VIRTUAL_CARDS, actions=Actions(read=True)),
            Scope(Product.CREDIT_CARDS, actions=Actions(read=True)),
            Scope(Product.TRANSACTIONS, actions=Actions(read=True)),
        ]
    )
)

# Create an agent with the tools
extend_agent = Agent(
    name="Extend Agent",
    instructions="You are an expert at integrating with Extend",
    tools=extend_openai_toolkit.get_tools()
)
```

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

### Integrate with OpenAI Agents

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Initialize the OpenAI toolkit and attach tools to an agent for managing Extend resources.

```python
import os
import asyncio
from agents import Agent, Runner
from dotenv import load_dotenv

from extend_ai_toolkit.openai.toolkit import ExtendOpenAIToolkit
from extend_ai_toolkit.shared import Configuration, Scope, Product, Actions

load_dotenv()

async def main():
	# Initialize the OpenAI toolkit with specific scopes
	extend_openai_toolkit = ExtendOpenAIToolkit.default_instance(
		api_key=os.environ.get("EXTEND_API_KEY"),
		api_secret=os.environ.get("EXTEND_API_SECRET"),
		configuration=Configuration(
			scope=[
				Scope(Product.VIRTUAL_CARDS, actions=Actions(read=True)),
				Scope(Product.CREDIT_CARDS, actions=Actions(read=True)),
				Scope(Product.TRANSACTIONS, actions=Actions(read=True)),
			]
		)
	)

	# Create an agent with Extend tools
	extend_agent = Agent(
		name="Extend Agent",
		instructions="You are an expert at integrating with Extend. You can help users manage virtual cards, view credit cards, and check transactions.",
		tools=extend_openai_toolkit.get_tools(),
		model="gpt-4o",
	)

	# Run the agent with a user query
	response = await Runner.run(extend_agent, "Show me all active virtual cards")
	print("Agent response:", response.final_output)

if __name__ == "__main__":
	asyncio.run(main())
```

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

### Initialize Extend LangChain Toolkit

Source: https://github.com/paywithextend/extend-ai-toolkit/blob/development/README.md

Initialize the Extend LangChain toolkit with API keys and a configuration scope. This prepares the toolkit for use with LangChain agents.

```python
import os
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent
from extend_ai_toolkit.langchain.toolkit import ExtendLangChainToolkit
from extend_ai_toolkit.shared import Configuration, Scope, Product, Actions

# Initialize the LangChain toolkit
extend_langchain_toolkit = ExtendLangChainToolkit.default_instance(
    api_key=os.environ.get("EXTEND_API_KEY"),
    api_secret=os.environ.get("EXTEND_API_SECRET"),
    configuration=Configuration(
        scope=[
            Scope(Product.VIRTUAL_CARDS, actions=Actions(read=True)),
            Scope(Product.CREDIT_CARDS, actions=Actions(read=True)),
            Scope(Product.TRANSACTIONS, actions=Actions(read=True)),
        ]
    )
)

# Create tools for the agent
tools = extend_langchain_toolkit.get_tools()

# Create the agent executor
langgraph_agent_executor = create_react_agent(
    ChatOpenAI(model="gpt-4"),
    tools
)
```

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

### Create CrewAI Agent with Extend Tools

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Initialize the Extend CrewAI toolkit, configure an LLM, and create an agent with a specific role and goal. Then, define tasks for the agent and execute them using a crew.

```python
import os
import asyncio
from dotenv import load_dotenv

from extend_ai_toolkit.crewai.toolkit import ExtendCrewAIToolkit
from extend_ai_toolkit.shared import Configuration, Scope, Product, Actions

load_dotenv()

async def main():
    # Initialize the CrewAI toolkit
    toolkit = ExtendCrewAIToolkit.default_instance(
        api_key=os.environ.get("EXTEND_API_KEY"),
        api_secret=os.environ.get("EXTEND_API_SECRET"),
        configuration=Configuration(
            scope=[
                Scope(Product.VIRTUAL_CARDS, actions=Actions(read=True)),
                Scope(Product.CREDIT_CARDS, actions=Actions(read=True)),
                Scope(Product.TRANSACTIONS, actions=Actions(read=True)),
            ]
        )
    )

    # Configure the LLM (using Claude)
    toolkit.configure_llm(
        model="claude-3-opus-20240229",
        api_key=os.environ.get("ANTHROPIC_API_KEY")
    )

    # Create an Extend integration agent
    extend_agent = toolkit.create_agent(
        role="Extend Integration Expert",
        goal="Help users manage virtual cards, view credit cards, and check transactions efficiently",
        backstory="You are an expert at integrating with Extend, with deep knowledge of virtual cards, credit cards, and transaction management.",
        verbose=True
    )

    # Create a task for the agent
    query_task = toolkit.create_task(
        description="List all virtual cards and summarize their status",
        agent=extend_agent,
        expected_output="A clear summary of all virtual cards with their status",
        async_execution=True
    )

    # Create a crew and execute
    crew = toolkit.create_crew(
        agents=[extend_agent],
        tasks=[query_task],
        verbose=True
    )

    result = crew.kickoff()
    print("Crew result:", result)

if __name__ == "__main__":
    asyncio.run(main())

```

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

### Configure Extend AI Toolkit

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Set up API credentials and define access scopes using the Configuration class.

```python
import os
from extend_ai_toolkit.shared import Configuration, Scope, Product, Actions

# Set environment variables
os.environ["EXTEND_API_KEY"] = "apik_your_api_key"
os.environ["EXTEND_API_SECRET"] = "your_api_secret"

# Create a configuration with specific scopes
configuration = Configuration(
	scope=[
		Scope(Product.VIRTUAL_CARDS, actions=Actions(read=True, update=True)),
		Scope(Product.CREDIT_CARDS, actions=Actions(read=True)),
		Scope(Product.TRANSACTIONS, actions=Actions(read=True, update=True)),
		Scope(Product.EXPENSE_CATEGORIES, actions=Actions(read=True, create=True, update=True)),
		Scope(Product.RECEIPT_ATTACHMENTS, actions=Actions(read=True, create=True)),
	]
)

# Or enable all tools at once
all_tools_config = Configuration.all_tools()
```

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

### Initialize Extend CrewAI Toolkit

Source: https://github.com/paywithextend/extend-ai-toolkit/blob/development/README.md

Initialize the Extend CrewAI toolkit with API keys and a configuration scope. This sets up the toolkit for integration with CrewAI agents.

```python
import os
from extend_ai_toolkit.crewai.toolkit import ExtendCrewAIToolkit
from extend_ai_toolkit.shared import Configuration, Scope, Product, Actions

# Initialize the CrewAI toolkit
toolkit = ExtendCrewAIToolkit.default_instance(
    api_key=os.environ.get("EXTEND_API_KEY"),
    api_secret=os.environ.get("EXTEND_API_SECRET"),
    configuration=Configuration(
        scope=[
            Scope(Product.VIRTUAL_CARDS, actions=Actions(read=True)),
            Scope(Product.CREDIT_CARDS, actions=Actions(read=True)),
            Scope(Product.TRANSACTIONS, actions=Actions(read=True)),
        ]
    )
)

# Configure the LLM (using Claude)
toolkit.configure_llm(
    model="claude-3-opus-20240229",
    api_key=os.environ.get("ANTHROPIC_API_KEY")
)
```

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

### Configure Extend MCP Server for Claude Desktop

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

This JSON configuration sets up an Extend MCP server for Claude Desktop integration, enabling access to all Extend tools and specifying API credentials. It also includes a configuration for a filesystem MCP server.

```json
{
  "mcpServers": {
    "extend-mcp": {
      "command": "python",
      "args": [
        "-m",
        "extend_ai_toolkit.modelcontextprotocol.main",
        "--tools=all"
      ],
      "env": {
        "EXTEND_API_KEY": "apik_XXXX",
        "EXTEND_API_SECRET": "XXXXX"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/receipts/folder"
      ]
    }
  }
}

```

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

### Implement Custom Authorization

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Configure authentication using Bearer tokens or API key/secret pairs for paywithextend 2.0+.

```python
from extend.auth import BearerAuth
from extend_ai_toolkit.shared import ExtendAPI

# Create an ExtendAPI instance with bearer token authentication
extend_api = ExtendAPI.from_auth(BearerAuth(jwt_token="your-jwt-token"))

# Or use basic auth with API key/secret (backwards compatible)
extend_api = ExtendAPI.default_instance(
	api_key="apik_your_api_key",
	api_secret="your_api_secret"
)
```

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

### Configure Extend API Key and Secret

Source: https://github.com/paywithextend/extend-ai-toolkit/blob/development/README.md

Configure your Extend API key and secret using command-line arguments or environment variables.

```sh
--api-key=your_api_key_here --api-secret=your_api_secret_here
```

```sh
EXTEND_API_KEY=your_api_key_here
EXTEND_API_SECRET=your_api_secret_here
```

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

### Test MCP Server Locally with Inspector

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Run the MCP server with all tools enabled using the inspector command. This command is useful for local development and testing of the MCP server functionality.

```bash
# Run MCP server with all tools enabled
npx @modelcontextprotocol/inspector python extend_ai_toolkit/modelcontextprotocol/main.py --tools=all

```

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

### Create and Run Extend Agent Crew

Source: https://github.com/paywithextend/extend-ai-toolkit/blob/development/README.md

Defines an agent, a task, and a crew for managing Extend integration queries, then initiates the crew's execution. Ensure the toolkit is imported before use.

```python
extend_agent = toolkit.create_agent(
    role="Extend Integration Expert",
    goal="Help users manage virtual cards, view credit cards, and check transactions efficiently",
    backstory="You are an expert at integrating with Extend, with deep knowledge of virtual cards, credit cards, and transaction management.",
    verbose=True
)

query_task = toolkit.create_task(
    description="Process and respond to user queries about Extend services",
    agent=extend_agent,
    expected_output="A clear and helpful response addressing the user's query",
    async_execution=True
)

crew = toolkit.create_crew(
    agents=[extend_agent],
    tasks=[query_task],
    verbose=True
)

result = crew.kickoff()
```

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

### Scope Configuration API

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Define granular permissions for toolkit operations using the Scope and Product system.

```APIDOC
## Scope Configuration

### Description
Define granular permissions for toolkit operations using the Scope and Product system.

### Available Products
- **Product.VIRTUAL_CARDS**: Virtual card operations
- **Product.CREDIT_CARDS**: Credit card operations
- **Product.TRANSACTIONS**: Transaction operations
- **Product.EXPENSE_CATEGORIES**: Expense category management
- **Product.RECEIPT_ATTACHMENTS**: Receipt upload and matching

### Available Actions
- **read**: View/list resources
- **create**: Create new resources
- **update**: Modify existing resources

### Examples

#### Read-only access to cards and transactions
```python
from extend_ai_toolkit.shared import Configuration, Scope, Product, Actions

read_only_config = Configuration(
    scope=[
        Scope(Product.VIRTUAL_CARDS, actions=Actions(read=True)),
        Scope(Product.CREDIT_CARDS, actions=Actions(read=True)),
        Scope(Product.TRANSACTIONS, actions=Actions(read=True)),
    ]
)
```

#### Full access to expense management
```python
from extend_ai_toolkit.shared import Configuration, Scope, Product, Actions

expense_management_config = Configuration(
    scope=[
        Scope(Product.TRANSACTIONS, actions=Actions(read=True, update=True)),
        Scope(Product.EXPENSE_CATEGORIES, actions=Actions(read=True, create=True, update=True)),
        Scope(Product.RECEIPT_ATTACHMENTS, actions=Actions(read=True, create=True)),
    ]
)
```

#### Enable all available tools
```python
from extend_ai_toolkit.shared import Configuration

all_tools_config = Configuration.all_tools()
```

#### Create configuration from tool string
```python
from extend_ai_toolkit.shared import Configuration

config_from_str = Configuration.from_tool_str("virtual_cards.read,transactions.read,credit_cards.read")
```
```

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

### Run MCP with specific tools

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Execute the MCP inspector with a restricted set of tools.

```bash
npx @modelcontextprotocol/inspector python extend_ai_toolkit/modelcontextprotocol/main.py --tools=virtual_cards.read,transactions.read,credit_cards.read
```

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

### Connect to Remote MCP Server using Client

Source: https://github.com/paywithextend/extend-ai-toolkit/blob/development/README.md

Optionally connect to a running remote MCP server using the MCP terminal client. Specify the host, port, and LLM provider details.

```bash
python -m extend_ai_toolkit.modelcontextprotocol.client.mcp_client --mcp-server-host localhost --mcp-server-port 8000 --llm-provider=anthropic --llm-model=claude-3-5-sonnet-20241022
```

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

### Load and validate environment variables

Source: https://github.com/paywithextend/extend-ai-toolkit/blob/development/extend_ai_toolkit/notebooks/langchain-react-agent.ipynb

Loads API key and secret from environment variables using dotenv. Raises a ValueError if 'EXTEND_API_KEY' or 'EXTEND_API_SECRET' are not set.

```python
# Load environment variables
load_dotenv()

# Get required environment variables
api_key = os.environ.get("EXTEND_API_KEY")
api_secret = os.environ.get("EXTEND_API_SECRET")

# Validate environment variables
if not all([api_key, api_secret]):
    raise ValueError("Missing required environment variables. Please set EXTEND_API_KEY and  EXTEND_API_SECRET")
```

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

### Create Receipt Attachment

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Uploads a receipt image and attaches it to a specific transaction. Supports various image and PDF formats.

```python
from extend_ai_toolkit.shared import ExtendAPI

extend_api = ExtendAPI.default_instance(api_key="apik_xxx", api_secret="secret")

# Upload a receipt and attach to a transaction
result = await extend_api.run(
    "create_receipt_attachment",
    transaction_id="txn_abc123",
    file_path="/path/to/receipt.png"  # Supports: PNG, JPG, JPEG, GIF, BMP, TIFF, HEIC, PDF
)

# Response includes:
# - id: Unique receipt attachment ID
# - transactionId: Associated transaction
# - contentType: MIME type
# - urls: Original, main, and thumbnail URLs
# - createdAt: Timestamp
print(result)
```

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

### Custom Authorization with BearerAuth (paywithextend 2.0+)

Source: https://github.com/paywithextend/extend-ai-toolkit/blob/development/README.md

Use custom authorization strategies like BearerAuth when using paywithextend version 2.0.0 or higher. For older versions, continue using api_key and api_secret.

```python
from extend.auth import BearerAuth
from extend_ai_toolkit.shared import ExtendAPI

extend_api = ExtendAPI.from_auth(BearerAuth(jwt_token="your-jwt-token"))
```

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

### Fetch virtual cards

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Retrieve a paginated list of virtual cards with optional filtering and sorting.

```python
from extend_ai_toolkit.shared import ExtendAPI

extend_api = ExtendAPI.default_instance(api_key="apik_xxx", api_secret="secret")

# Get all active virtual cards, sorted by creation date
result = await extend_api.run(
    "get_virtual_cards",
    page=0,
    per_page=10,
    status="ACTIVE",  # Options: ACTIVE, CANCELLED, PENDING, EXPIRED, CLOSED, CONSUMED
    sort_field="createdAt",
    sort_direction="DESC"
)

# Search for virtual cards by term
result = await extend_api.run(
    "get_virtual_cards",
    search_term="marketing",
    status="ACTIVE"
)

# Filter by recipient
result = await extend_api.run(
    "get_virtual_cards",
    recipient="user@example.com"
)
```

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

### Fetch transactions

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Retrieve transactions using various filters like date range, status, and amount.

```python
from extend_ai_toolkit.shared import ExtendAPI

extend_api = ExtendAPI.default_instance(api_key="apik_xxx", api_secret="secret")

# Get recent transactions
result = await extend_api.run(
    "get_transactions",
    page=0,
    per_page=50,
    from_date="2024-01-01",
    to_date="2024-12-31",
    sort_field="-date"  # Descending order by date
)

# Filter by status
result = await extend_api.run(
    "get_transactions",
    status="CLEARED"  # Options: PENDING, CLEARED, DECLINED
)

# Filter by amount range
result = await extend_api.run(
    "get_transactions",
    min_amount_cents=10000,  # $100.00 minimum
    max_amount_cents=100000  # $1000.00 maximum
)

# Find transactions missing receipts
result = await extend_api.run(
    "get_transactions",
    receipt_missing=True
)

# Filter by specific virtual card
result = await extend_api.run(
    "get_transactions",
    virtual_card_id="vc_abc123def456"
)
```

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

### Create expense category

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Creates a new expense category for the organization.

```python
from extend_ai_toolkit.shared import ExtendAPI

extend_api = ExtendAPI.default_instance(api_key="apik_xxx", api_secret="secret")

# Create a new expense category
result = await extend_api.run(
    "create_expense_category",
    name="Marketing Expenses",
    code="MKTG",
    required=True,
    active=True,
    free_text_allowed=False
)

print(result)  # Returns the created category details
```

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

### Fetch credit cards

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Retrieve a paginated list of credit cards with filtering options.

```python
from extend_ai_toolkit.shared import ExtendAPI

extend_api = ExtendAPI.default_instance(api_key="apik_xxx", api_secret="secret")

# Get all credit cards
result = await extend_api.run(
    "get_credit_cards",
    page=0,
    per_page=10,
    sort_direction="DESC"
)

# Search for credit cards by term
result = await extend_api.run(
    "get_credit_cards",
    search_term="corporate"
)

# Filter by status
result = await extend_api.run(
    "get_credit_cards",
    status="ACTIVE"
)
```

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

### Create expense category label

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Adds a new label to an existing expense category.

```python
from extend_ai_toolkit.shared import ExtendAPI

extend_api = ExtendAPI.default_instance(api_key="apik_xxx", api_secret="secret")

# Create a new label for an expense category
result = await extend_api.run(
    "create_expense_category_label",
    category_id="cat_marketing",
    name="Digital Advertising",
    code="DIGITAL_ADS",
    active=True
)

print(result)  # Returns the created label details
```

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

### get_credit_cards

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Fetch a paginated list of credit cards associated with the account.

```APIDOC
## get_credit_cards

### Description
Fetch a paginated list of credit cards associated with the account.

### Parameters
#### Request Body
- **page** (integer) - Optional - Page number for pagination
- **per_page** (integer) - Optional - Number of items per page
- **sort_direction** (string) - Optional - Sort direction
- **search_term** (string) - Optional - Search term for filtering
- **status** (string) - Optional - Filter by status
```

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

### Automatch Receipts

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Initiates an asynchronous job to automatically match a list of uploaded receipts to their corresponding transactions. Returns a job ID for status tracking.

```python
from extend_ai_toolkit.shared import ExtendAPI

extend_api = ExtendAPI.default_instance(api_key="apik_xxx", api_secret="secret")

# Start automatch job for multiple receipts
result = await extend_api.run(
    "automatch_receipts",
    receipt_attachment_ids=[
        "rcpt_abc123",
        "rcpt_def456",
        "rcpt_ghi789"
    ]
)

# Response includes job_id for status tracking
job_id = result.get("jobId")
print(f"Automatch job started: {job_id}")
```

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

### get_credit_card_detail

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Retrieve detailed information about a specific credit card.

```APIDOC
## get_credit_card_detail

### Description
Retrieve detailed information about a specific credit card.

### Parameters
#### Request Body
- **credit_card_id** (string) - Required - The unique identifier of the credit card
```

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

### Retrieve transaction details

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Fetches comprehensive data for a specific transaction, including expense categories and receipt status.

```python
from extend_ai_toolkit.shared import ExtendAPI

extend_api = ExtendAPI.default_instance(api_key="apik_xxx", api_secret="secret")

# Get detailed transaction information
result = await extend_api.run(
    "get_transaction_detail",
    transaction_id="txn_abc123"
)

# Response includes: amount, merchant, date, status, expense categories, receipts, etc.
print(result)
```

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

### Automatch Receipts API

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Initiate an asynchronous job to automatically match uploaded receipts to transactions.

```APIDOC
## POST /paywithextend/extend-ai-toolkit/automatch_receipts

### Description
Initiate an asynchronous job to automatically match uploaded receipts to transactions.

### Method
POST

### Endpoint
/paywithextend/extend-ai-toolkit/automatch_receipts

### Parameters
#### Request Body
- **receipt_attachment_ids** (array of strings) - Required - A list of receipt attachment IDs to be matched.

### Request Example
```json
{
  "receipt_attachment_ids": [
    "rcpt_abc123",
    "rcpt_def456",
    "rcpt_ghi789"
  ]
}
```

### Response
#### Success Response (200)
- **jobId** (string) - The ID of the initiated automatch job, used for status tracking.

#### Response Example
```json
{
  "jobId": "job_xyz789"
}
```
```

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

### Send Receipt Reminder

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Sends an email reminder to a cardholder for a transaction that is missing a receipt. Confirms that the reminder has been sent.

```python
from extend_ai_toolkit.shared import ExtendAPI

extend_api = ExtendAPI.default_instance(api_key="apik_xxx", api_secret="secret")

# Send receipt reminder for a transaction
result = await extend_api.run(
    "send_receipt_reminder",
    transaction_id="txn_abc123"
)

print(result)  # Confirmation that reminder was sent
```

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

### Retrieve expense categories

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Fetches expense categories with optional filtering by status or search terms.

```python
from extend_ai_toolkit.shared import ExtendAPI

extend_api = ExtendAPI.default_instance(api_key="apik_xxx", api_secret="secret")

# Get all expense categories
result = await extend_api.run(
    "get_expense_categories"
)

# Filter by active status
result = await extend_api.run(
    "get_expense_categories",
    active=True
)

# Filter by required status
result = await extend_api.run(
    "get_expense_categories",
    required=True
)

# Search categories
result = await extend_api.run(
    "get_expense_categories",
    search="travel",
    sort_field="name",
    sort_direction="ASC"
)
```

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

### Create Receipt Attachment API

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Upload a receipt image and optionally attach it to a transaction. Supports various image and PDF formats.

```APIDOC
## POST /paywithextend/extend-ai-toolkit/create_receipt_attachment

### Description
Upload a receipt image and optionally attach it to a transaction.

### Method
POST

### Endpoint
/paywithextend/extend-ai-toolkit/create_receipt_attachment

### Parameters
#### Query Parameters
- **transaction_id** (string) - Required - The ID of the transaction to attach the receipt to.
- **file_path** (string) - Required - The local path to the receipt file. Supports: PNG, JPG, JPEG, GIF, BMP, TIFF, HEIC, PDF.

### Request Example
```json
{
  "transaction_id": "txn_abc123",
  "file_path": "/path/to/receipt.png"
}
```

### Response
#### Success Response (200)
- **id** (string) - Unique receipt attachment ID.
- **transactionId** (string) - Associated transaction ID.
- **contentType** (string) - MIME type of the uploaded file.
- **urls** (object) - Object containing original, main, and thumbnail URLs.
- **createdAt** (string) - Timestamp of when the receipt was created.

#### Response Example
```json
{
  "id": "rcpt_xyz789",
  "transactionId": "txn_abc123",
  "contentType": "image/png",
  "urls": {
    "original": "http://example.com/original.png",
    "main": "http://example.com/main.png",
    "thumbnail": "http://example.com/thumbnail.png"
  },
  "createdAt": "2023-10-27T10:00:00Z"
}
```
```

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

### Search transactions by merchant name

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Executes a search for transactions matching a specific merchant name.

```python
result = await extend_api.run(
    "get_transactions",
    search_term="Amazon"
)
```

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

### Create Expense Category

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Creates a new expense category for the organization.

```APIDOC
## POST /expense_categories

### Description
Create a new expense category for the organization.

### Method
POST

### Endpoint
/expense_categories

### Request Body
- **name** (string) - Required - The name of the expense category.
- **code** (string) - Required - The code for the expense category.
- **required** (boolean) - Optional - Whether the category is required (defaults to false).
- **active** (boolean) - Optional - Whether the category is active (defaults to true).
- **free_text_allowed** (boolean) - Optional - Whether free text is allowed (defaults to false).

### Request Example
```json
{
  "name": "Marketing Expenses",
  "code": "MKTG",
  "required": true,
  "active": true,
  "free_text_allowed": false
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the newly created category.
- **name** (string) - The name of the category.
- **code** (string) - The code of the category.
- **required** (boolean) - The required status.
- **active** (boolean) - The active status.
- **free_text_allowed** (boolean) - The free text allowed status.

### Response Example
```json
{
  "id": "cat_mktg",
  "name": "Marketing Expenses",
  "code": "MKTG",
  "required": true,
  "active": true,
  "free_text_allowed": false
}
```
```

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

### Retrieve expense category labels

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Fetches labels associated with a specific category, supporting pagination and filtering.

```python
from extend_ai_toolkit.shared import ExtendAPI

extend_api = ExtendAPI.default_instance(api_key="apik_xxx", api_secret="secret")

# Get all labels for an expense category
result = await extend_api.run(
    "get_expense_category_labels",
    category_id="cat_travel",
    page=0,
    per_page=50
)

# Filter active labels only
result = await extend_api.run(
    "get_expense_category_labels",
    category_id="cat_travel",
    active=True
)

# Search for specific labels
result = await extend_api.run(
    "get_expense_category_labels",
    category_id="cat_travel",
    search="flight",
    sort_field="name",
    sort_direction="ASC"
)
```

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

### get_virtual_cards

Source: https://context7.com/paywithextend/extend-ai-toolkit/llms.txt

Fetch a paginated list of virtual cards with optional filters for status, recipient, and sorting.

```APIDOC
## get_virtual_cards

### Description
Fetch a paginated list of virtual cards with optional filters for status, recipient, and sorting.

### Parameters
#### Request Body
- **page** (integer) - Optional - Page number for pagination
- **per_page** (integer) - Optional - Number of items per page
- **status** (string) - Optional - Filter by status (ACTIVE, CANCELLED, PENDING, EXPIRED, CLOSED, CONSUMED)
- **sort_field** (string) - Optional - Field to sort by
- **sort_direction** (string) - Optional - Sort direction (ASC, DESC)
- **search_term** (string) - Optional - Search term for filtering
- **recipient** (string) - Optional - Filter by recipient email
```