Exposing an AI Agent as an MCP Server with MAF — Part 6 : How to Add a New Agent to the MAF Multi-Agent Server

The Short Answer#

Adding a new agent requires creating exactly two files:

jira_tools.py — the tool functions
agents/jira_agent.yaml — the agent config

Nothing else changes. server.py discovers the new YAML file automatically on next startup.

What You Are Not Changing#

It is worth being explicit about this before anything else. You do not touch:

server.py — it discovers all *.yaml files in agents/ automatically
tools.py — each agent has its own tools module, they do not share one
Any existing agent files — the ServiceNow agent continues running unchanged
.env — the Azure OpenAI credentials are shared across all agents

Step 1: Write the Tools#

Create jira_tools.py in the project root. Each function must use @ai_function and Annotated type hints — this is how server.py derives REST schemas, registry entries, and the ChatAgent tool set without any manual schema definition.

1
from typing import Annotated
2
from agent_framework import ai_function
3

4

5
@ai_function
6
def create_issue(
7
    project_key: Annotated[str, "Jira project key e.g. PLAT, ENG, OPS."],
8
    summary:     Annotated[str, "One-line summary of the issue (5–255 chars)."],
9
    issue_type:  Annotated[str, "Issue type: Bug | Story | Task | Epic."] = "Task",
10
    priority:    Annotated[str, "Priority: Highest | High | Medium | Low | Lowest."] = "Medium",
11
) -> Annotated[str, "Confirmation with issue key, summary, type, and priority."]:
12
    """Creates a new issue in Jira."""
13
    return (
14
        f"Issue created.\n"
15
        f"  Key:      {project_key}-1042\n"
16
        f"  Summary:  {summary}\n"
17
        f"  Type:     {issue_type}\n"
18
        f"  Priority: {priority}\n"
19
        f"  Status:   To Do"
20
    )
21

22

23
@ai_function
24
def update_issue(
25
    issue_key:  Annotated[str, "Jira issue key e.g. PLAT-1042."],
26
    status:     Annotated[str, "New status: In Progress | In Review | Done | Blocked."],
27
    comment:    Annotated[str, "Comment to add to the issue (max 5000 chars)."] = "",
28
) -> Annotated[str, "Confirmation with issue key, new status, and comment."]:
29
    """Updates the status and adds a comment to an existing Jira issue."""
30
    return (
31
        f"Issue updated.\n"
32
        f"  Key:     {issue_key}\n"
33
        f"  Status:  {status}\n"
34
        f"  Comment: {comment or 'None added'}"
35
    )
36

37

38
@ai_function
39
def search_issues(
40
    query: Annotated[str, "JQL query or keyword to search issues (1–500 chars)."],
41
) -> Annotated[str, "Matching issues with key, summary, status, and priority."]:
42
    """Searches Jira issues using JQL or plain keywords."""
43
    return (
44
        f"Results for '{query}':\n"
45
        f"  1. PLAT-1040 — API rate limiting      — In Progress — High\n"
46
        f"  2. PLAT-1041 — Login page broken      — In Review   — Highest\n"
47
        f"  3. PLAT-1042 — Update dependencies    — To Do       — Medium"
48
    )

Rules for Tool Functions#

Every tool function must follow these conventions or server.py will either fail to load it or generate incorrect REST routes and schemas:

The function must be decorated with @ai_function. Without this, load_tools() will still find the function by name, but the ChatAgent will not be able to use it.

Every parameter must have an Annotated[type, "description"] hint. The description string is used in the registry schema and in the Swagger UI. A parameter without an Annotated hint will default to string type and have an empty description.

The docstring becomes the endpoint summary in Swagger and the tool description in the registry. Keep it to one line and write it as a verb phrase — Creates a new issue in Jira, not This function creates issues.

Write operations must include one of create, update, delete, or set in the function name. server.py uses this convention to decide whether to generate a POST or GET endpoint. A function named create_issue becomes POST /create_issue. A function named search_issues becomes GET /search_issues.

Step 2: Write the YAML Config#

Create agents/jira_agent.yaml. Copy the structure from an existing agent file and change the values:

1
agent:
2
  # ── Identity ───────────────────────────────────────────────────
3
  name: JiraAgent
4
  display_name: Jira Issue Manager
5
  description: Creates, updates, and searches Jira issues across projects.
6
  version: "1.0.0"
7
  tags:
8
    - jira
9
    - project-management
10

11
  # ── Ports ──────────────────────────────────────────────────────
12
  ports:
13
    rest: 8010
14
    mcp: 8011
15

16
  # ── Tools ──────────────────────────────────────────────────────
17
  module: jira_tools
18
  tools:
19
    - create_issue
20
    - update_issue
21
    - search_issues
22

23
  # ── Behaviour ──────────────────────────────────────────────────
24
  instructions: |
25
    You are a Jira assistant. Use your tools to manage issues across projects.
26
    Always include the issue key in your response.
27
    When issue type is not specified, default to Task.
28
    When priority is not specified, default to Medium.

Rules for the YAML File#

name must be unique across all agents and must start with a letter followed only by letters, numbers, hyphens, or underscores. It is used as the key in the registry, as the identifier in the MCP server, and in the deregistration call on shutdown. JiraAgent is fine. Jira Agent (with a space) is not — Pydantic will reject it at startup.

ports.rest and ports.mcp must both be unique across the entire agents/ directory. server.py checks all YAML files for port collisions before starting any servers. If two agents share a port, the whole process exits with a clear error. Use ports above 1024.

module is the Python module name — the filename without .py. Since jira_tools.py is in the project root and server.py adds the project root to sys.path, the module name is simply jira_tools.

tools is the list of function names to import from that module. Each name must exactly match a function defined in jira_tools.py. A typo here will raise a ValueError at startup naming the missing function.

instructions is the system prompt for the ChatAgent. Use YAML’s block scalar (|) for multi-line prompts — it preserves line breaks cleanly without escaping.

Step 3: Start the Server#

1
python server.py

1
  [Registry] http://localhost:8002/registry
2

3
  [ServiceNowAgent] REST → http://localhost:8000/docs
4
  [ServiceNowAgent] MCP  → http://localhost:8001/sse
5
  [JiraAgent] REST → http://localhost:8010/docs
6
  [JiraAgent] MCP  → http://localhost:8011/sse

Both agents are running. The registry now knows about both:

1
curl http://localhost:8002/registry

1
{
2
  "total": 2,
3
  "agents": [
4
    { "name": "ServiceNowAgent", ... },
5
    { "name": "JiraAgent", ... }
6
  ]
7
}

To verify the Jira agent’s tool schemas registered correctly:

1
curl http://localhost:8002/registry/JiraAgent/tools

1
{
2
  "agent": "JiraAgent",
3
  "tools": [
4
    {
5
      "name": "create_issue",
6
      "description": "Creates a new issue in Jira.",
7
      "category": "write",
8
      "input_schema": {
9
        "type": "object",
10
        "required": ["project_key", "summary"],
11
        "properties": {
12
          "project_key": { "type": "string", "description": "Jira project key e.g. PLAT, ENG, OPS." },
13
          "summary":     { "type": "string", "description": "One-line summary of the issue (5–255 chars)." },
14
          "issue_type":  { "type": "string", "description": "Issue type: Bug | Story | Task | Epic.", "default": "Task" },
15
          "priority":    { "type": "string", "description": "Priority: Highest | High | Medium | Low | Lowest.", "default": "Medium" }
16
        }
17
      }
18
    },
19
    ...
20
  ]
21
}

To start only the Jira agent in isolation — useful during development:

1
python server.py agents/jira_agent.yaml

What Startup Validation Catches#

Before any server starts, server.py validates every YAML file and raises a clear error if anything is wrong. Here is what each error looks like and how to fix it:

Missing required field:

1
ValueError: Invalid config in 'agents/jira_agent.yaml':
2
  1 validation error for AgentConfig
3
  name
4
    Field required [type=missing]

Fix: add the missing field to the YAML.

Invalid name format (contains a space):

1
ValueError: Invalid config in 'agents/jira_agent.yaml':
2
  1 validation error for AgentConfig
3
  name
4
    String should match pattern '^[A-Za-z][A-Za-z0-9_-]*$'

Fix: remove spaces and special characters from name. Use JiraAgent not Jira Agent.

rest and mcp ports are the same:

1
ValueError: Invalid config in 'agents/jira_agent.yaml':
2
  1 validation error for AgentConfig
3
  ports.mcp
4
    Value error, mcp port must differ from rest port

Fix: give rest and mcp different port numbers.

Port collision between two agents:

1
ValueError: Port 8000 is used by more than one agent.

Fix: change the port in one of the conflicting YAML files.

Tool function not found in module:

1
ValueError: Tool 'create_issue' not found in module 'jira_tools'.

Fix: check the spelling in both the YAML tools list and the function name in jira_tools.py.

Complete File Checklist#

When adding a new agent, create these two files and nothing else:

1
project/
2
├── agents/
3
│   ├── servicenow_agent.yaml   ← unchanged
4
│   └── jira_agent.yaml         ← NEW
5
├── jira_tools.py               ← NEW
6
├── tools.py                    ← unchanged
7
├── server.py                   ← unchanged
8
└── .env                        ← unchanged

This guide is part of a series on building multi-agent systems with Microsoft Agent Framework.

← Part 4: Three Interfaces | ← Part 5: YAML Config