Outlook MCP Email
Read, search and triage emails in a Microsoft 365 / Outlook mailbox, draft replies and (optionally) send email.
Quick start
- Add a Outlook connection with the settings below, then click Test configuration.
- Create an API key for your agent.
- Paste the key below, click Test endpoint, and copy the configuration for your platform.
| Endpoint | https://market.oshaani.com/outlook (your default connection) or https://market.oshaani.com/outlook/<connection-id> |
|---|---|
| Transport | Streamable HTTP (stateless, JSON responses). MCP protocol versions 2024-11-05 to 2025-11-25 and 2026-07-28. |
| Authentication | Authorization: Bearer <API key>, using a key from the API keys page. |
Agent configuration
initialize and tools/list against the endpoint, exactly like an agent. No credits are charged.
Any MCP client that supports remote (Streamable HTTP) servers with custom headers.
{
"name": "outlook",
"transport": "streamable-http",
"url": "https://market.oshaani.com/outlook",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
~/.cursor/mcp.json (all projects) or .cursor/mcp.json in a project.
{
"mcpServers": {
"outlook": {
"url": "https://market.oshaani.com/outlook",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
Settings > Developer > Edit Config (claude_desktop_config.json). Uses the mcp-remote bridge; needs Node.js.
{
"mcpServers": {
"outlook": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://market.oshaani.com/outlook",
"--header",
"Authorization:${AUTH_HEADER}"
],
"env": {
"AUTH_HEADER": "Bearer YOUR_API_KEY"
}
}
}
}
Run in your terminal, or put the JSON in .mcp.json at the project root.
claude mcp add --transport http outlook https://market.oshaani.com/outlook \
--header "Authorization: Bearer YOUR_API_KEY"
# .mcp.json
{
"mcpServers": {
"outlook": {
"type": "http",
"url": "https://market.oshaani.com/outlook",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
.vscode/mcp.json (GitHub Copilot agent mode). VS Code prompts for the key once and stores it securely.
{
"inputs": [
{
"type": "promptString",
"id": "oshaani-mcp-key",
"description": "oshaani MCP Marketplace API key",
"password": true
}
],
"servers": {
"outlook": {
"type": "http",
"url": "https://market.oshaani.com/outlook",
"headers": {
"Authorization": "Bearer ${input:oshaani-mcp-key}"
}
}
}
}
~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"outlook": {
"serverUrl": "https://market.oshaani.com/outlook",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
Responses API remote MCP tool (Python SDK).
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-4.1",
tools=[{
"type": "mcp",
"server_label": "outlook",
"server_url": "https://market.oshaani.com/outlook",
"headers": {"Authorization": "Bearer YOUR_API_KEY"},
"require_approval": "never", # or "always" to approve each tool call
}],
input="What can you do with these tools?",
)
print(response.output_text)
Messages API MCP connector (Python SDK).
import anthropic
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
messages=[{"role": "user", "content": "What can you do with these tools?"}],
mcp_servers=[{
"type": "url",
"url": "https://market.oshaani.com/outlook",
"name": "outlook",
"authorization_token": "YOUR_API_KEY",
}],
betas=["mcp-client-2025-04-04"],
)
print(response.content)
Official MCP Python SDK 2.x (pip install mcp); works inside any agent framework.
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import create_mcp_http_client, streamable_http_client
async def main():
headers = {"Authorization": "Bearer YOUR_API_KEY"}
async with create_mcp_http_client(headers=headers) as http:
async with streamable_http_client("https://market.oshaani.com/outlook", http_client=http) as (read, write, *_):
async with ClientSession(read, write) as session:
await session.initialize()
tools = await session.list_tools()
print([tool.name for tool in tools.tools])
asyncio.run(main())
Quick check from a terminal: lists the tools without charging credits.
curl -s https://market.oshaani.com/outlook \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "MCP-Protocol-Version: 2025-06-18" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
Connection settings
Entered once per connection on market.oshaani.com. Secrets are encrypted and never shown again or sent to agents.
| Setting | Type | Description |
|---|---|---|
Directory (tenant) IDtenant_id
required |
string | pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ |
Application (client) IDclient_id
required |
string | pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ |
Client secretclient_secret
required secret |
string | App registration > Certificates & secrets |
Mailboxmailbox
required |
string | The mailbox this connection works on, e.g. sales@contoso.com pattern ^[^@\s/\\]+@[^@\s/\\]+\.[^@\s/\\]+$ |
Allow drafting, marking as read and moving emailsallow_write_actions
|
boolean default false |
Needs the Mail.ReadWrite application permission |
Allow sending emails and repliesallow_sending
|
boolean default false |
Needs the Mail.Send application permission. Off by default: agents can only read until this is enabled. |
Allowed recipient domainsallowed_recipient_domains
|
string | Comma-separated, e.g. contoso.com,partner.com. Sending to any other domain is refused. Leave empty to allow any. |
Tools (10)
list_folders
read-only
List mail folders with unread and total counts
No arguments.
list_messages
read-only
List emails in a folder, newest first, optionally only unread, from a sender or since a date
| Argument | Type | Description |
|---|---|---|
folder |
string default "inbox" |
Folder ID, or a well-known name: inbox, sentitems, drafts, archive, deleteditems, junkemail pattern ^[A-Za-z0-9=_+\-]{1,400}$ |
unread_only |
boolean default false |
|
from_address |
string | Only emails from this address pattern ^[^@\s/\\]+@[^@\s/\\]+\.[^@\s/\\]+$ |
since |
string (date) | Only emails received on or after this date (UTC) |
top |
integer default 25 |
Number of messages (max 100) min 1, max 100 |
skip |
integer default 0 |
min 0 |
search_messages
read-only
Search the whole mailbox with keywords or KQL, e.g. 'invoice from:billing@acme.com'
| Argument | Type | Description |
|---|---|---|
query required |
string | min length 1, max length 500 |
top |
integer default 25 |
Number of messages (max 100) min 1, max 100 |
get_message
read-only
Read an email: sender, recipients, plain-text body and attachment list
| Argument | Type | Description |
|---|---|---|
message_id required |
string | Message ID from list_messages or search_messages pattern ^[A-Za-z0-9=_+\-/]{10,400}$ |
max_body_chars |
integer default 20000 |
min 200, max 100000 |
get_attachment
read-only
Read a text attachment (txt, csv, json, xml...) of an email
| Argument | Type | Description |
|---|---|---|
message_id required |
string | Message ID from list_messages or search_messages pattern ^[A-Za-z0-9=_+\-/]{10,400}$ |
attachment_id required |
string | pattern ^[A-Za-z0-9=_+\-/]{10,800}$ |
max_chars |
integer default 50000 |
min 200, max 200000 |
create_draft
Save a draft email in the Drafts folder for a person to review and send
| Argument | Type | Description |
|---|---|---|
to required |
array of string | |
subject required |
string | min length 1, max length 255 |
body required |
string | max length 200000 |
cc |
array of string | |
body_type |
"text" | "html" default "text" |
send_email
destructive
Send an email from the mailbox
| Argument | Type | Description |
|---|---|---|
to required |
array of string | |
subject required |
string | min length 1, max length 255 |
body required |
string | max length 200000 |
cc |
array of string | |
bcc |
array of string | |
body_type |
"text" | "html" default "text" |
reply_to_message
destructive
Reply to an email (or reply all), quoting the original
| Argument | Type | Description |
|---|---|---|
message_id required |
string | Message ID from list_messages or search_messages pattern ^[A-Za-z0-9=_+\-/]{10,400}$ |
comment required |
string | Reply text placed above the quoted original min length 1, max length 200000 |
reply_all |
boolean default false |
mark_as_read
Mark an email as read or unread
| Argument | Type | Description |
|---|---|---|
message_id required |
string | Message ID from list_messages or search_messages pattern ^[A-Za-z0-9=_+\-/]{10,400}$ |
is_read |
boolean default true |
move_message
Move an email to another folder, e.g. archive or deleteditems
| Argument | Type | Description |
|---|---|---|
message_id required |
string | Message ID from list_messages or search_messages pattern ^[A-Za-z0-9=_+\-/]{10,400}$ |
destination_folder required |
string | Folder ID, or a well-known name: inbox, sentitems, drafts, archive, deleteditems, junkemail pattern ^[A-Za-z0-9=_+\-]{1,400}$ |
Billing & errors
Each successful tool call costs 1 oshaani.com credit. initialize, tools/list, failed calls and timeouts are free.
| JSON-RPC code | Meaning |
|---|---|
-32054 (HTTP 401) | Missing, unknown or revoked API key |
-32053 (HTTP 404) | No Outlook connection configured for your organisation, or the connection ID is wrong |
-32055 (HTTP 403) | Connection disabled or origin not allowed |
-32052 (HTTP 429) | Rate limit reached; retry after a minute |
-32050 | Not enough oshaani.com credits for the call |
-32051 | Billing temporarily unavailable; the call was not run |
Errors from Outlook itself (bad IDs, permissions) come back as tool results with isError: true so the agent can read and correct them.
See the Outlook API documentation.