Skip to content

update readme for openai playground sample #598

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

update readme for openai playground sample #598

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 40 additions & 23 deletions mcp-server/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Functions to run an MCP server for Twilio API tools

1. Install the [Twilio CLI](https://www.twilio.com/docs/twilio-cli/quickstart#install-twilio-cli)

Recommended method, homebrew:
Recommended method, homebrew:
```shell
brew tap twilio/brew && brew install twilio
twilio login
Expand Down Expand Up @@ -70,24 +70,25 @@ twilio serverless:deploy

ℹ️ We're aware of a reported issue with the MCP Inspector project and the authentication header. You'll need to use your MCP client to connect to your deployed MCP server.

## Integration with MCP clients

* **URL**: `https://{functions-domain}.twil.io/mcp?services=`
* **Authentication Header**:
* Key: `x-twilio-signature`
* Value: {Valid Twilio signature}
## Generatin Twilio Signature
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Typo, but I'd recommend:

Generating a Twilio signature


### Code samples for generating a Twilio signature

Learn more about the use of `x-twilio-signature` header for executing `protected` Functions. https://www.twilio.com/docs/serverless/functions-assets/visibility#protected
Learn more about the use of `x-twilio-signature` header for executing `protected` Functions. https://www.twilio.com/docs/serverless/functions-assets/visibility#protected

The sample code below assuming that the following environment variables are set:
* TWILIO_AUTH_TOKEN
* TWILIO_BASE_DOMAIN

ℹ️ As the generated signature depends on the full Function endpoint that you are executing, and the URL includes the set of services (e.g. `/mcp?services=PhoneNumbers` vs `/mcp?services=Messaging`), you will need to generate a valid signature every time you update any part of the URL. We recommend dynamically generating the signature whenever you initialize the MCP client configuration with your Twilio MCP server.
ℹ️ As the generated signature depends on the full Function endpoint that you are executing, and the URL includes the set of services (e.g. `/mcp?services=PhoneNumbers` vs `/mcp?services=Messaging`), you will need to generate a valid signature every time you update any part of the URL. We recommend dynamically generating the signature whenever you initialize the MCP client configuration with your Twilio MCP server.

### npx with [`twilio-signature-cli`](https://www.npmjs.com/package/twilio-signature-cli)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I had this under JavaScript because of npm; Python and Java and Go developers might not have npm installed. Just like I'd include conda or pip under Python.


#### JavaScript
This CLI tool makes it easy to generate Twilio signatures for webhook validation without writing any code. It's perfect for testing and debugging Twilio webhook integrations, or for generating signatures in automated scripts.

```shell
npx twilio-signature-cli -t TWILIO_AUTH_TOKEN -u YOUR_FUNCTION_URL
```

### JavaScript

```javascript
const crypto = require("crypto");
Expand Down Expand Up @@ -140,23 +141,15 @@ const dotenv = require("dotenv");

dotenv.config();

const signature =
const signature =
createTwilioSignature(
process.env.TWILIO_AUTH_TOKEN,
`${process.env.TWILIO_DOMAIN_NAME}/mcp?services=...`,
{}
);
```

#### npx with [`twilio-signature-cli`](https://www.npmjs.com/package/twilio-signature-cli)

This CLI tool makes it easy to generate Twilio signatures for webhook validation without writing any code. It's perfect for testing and debugging Twilio webhook integrations, or for generating signatures in automated scripts.

```shell
npx twilio-signature-cli -t TWILIO_AUTH_TOKEN -u YOUR_FUNCTION_URL
```

#### Python
### Python

```python
import os
Expand All @@ -171,7 +164,31 @@ validator = RequestValidator(auth_token)
signature = validator.compute_signature(url, {})
```

### Filtering tools by service
## Integration with MCP clients

* **URL**: `https://{functions-domain}.twil.io/mcp?services=`
* **Authentication Header**:
* Key: `x-twilio-signature`
* Value: {Valid Twilio signature}

### OpenAI Playground

You can use [OpenAI Playground](https://platform.openai.com/playground) to try out the Twilio MCP server.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

... to try out the your Twilio MCP server... ?


1) Follow the instructions here to first deploy your MCP server.
2) Visit [OpenAI Playground](https://platform.openai.com/playground) and click on `Create` in front of Tools. Then select `MCP Server` from the dropdown menu. Then select `Add new`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd make it Visit the OpenAI Playground and click..., adding "the"

3) Paste the URL of Twilio Functions MCP Server from step 1) in the URL `https://{functions-domain}.twil.io/mcp`. Include any services you want in the query parameter.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Paste the URL of (the|your) Twilio Functions MCP server from step 1) ...

4) For the `Authorization`, select `Custom headers`. For the header key, type in `x-twilio-signature`.
5) For the header value, open your terminal and type `npx twilio-signature-cli -t AUTH_TOKEN -u https://{functions-domain}.twil.io/mcp`. Copy the output and paste it in the header value
6) `Connect`

_NOTE_: You can filter different Twilio Services by using the query param `services` in the URL. For example `https://{functions-domain}.twil.io/mcp?services=Studio&services=PhoneNumbers` would give you `Studio` and `Phone Numbers` services. If you change this URL, remember to re-run the `npx twilio-signature-cli ...` with the updated URL (including the query params) to generate a new signature. For a list of all available services, visit [Twilio Functions](https://github.com/twilio-labs/function-templates/tree/main/mcp-server#filtering-tools-by-service).

### Javascript Code Sample

You can visit and clone https://github.com/twilio-samples/openai-mcp-samples/ for examples of how to use the MCP Server with OpenAI.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Visit [our OpenAI MCP samples repo](https://github.com/twilio-samples/openai-mcp-samples/) for examples of...


## Filtering tools by service

Use the querystring parameter `?services=` to specify a set of tools based on the needs of your MCP client. Set multiple services by passing multiple `services` key/value pairs.

Expand Down